hugo/docs/content/templates/base.md

133 lines
4.9 KiB
Markdown
Raw Normal View History

---
title: Base Templates and Blocks
linktitle:
description: The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page).
godocref: https://golang.org/pkg/text/template/#example_Template_block
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [templates,fundamentals]
keywords: [blocks,base]
menu:
docs:
parent: "templates"
weight: 20
weight: 20
sections_weight: 20
draft: false
aliases: [/templates/blocks/,/templates/base-templates-and-blocks/]
toc: true
---
The `block` keyword allows you to define the outer shell of your pages' one or more master template(s) and then fill in or override portions as necessary.
{{< youtube QVOMCYitLEc >}}
## Base Template Lookup Order
The [lookup order][lookup] for base templates is as follows:
1. `/layouts/section/<TYPE>-baseof.html`
2. `/themes/<THEME>/layouts/section/<TYPE>-baseof.html`
3. `/layouts/<TYPE>/baseof.html`
4. `/themes/<THEME>/layouts/<TYPE>/baseof.html`
5. `/layouts/section/baseof.html`
6. `/themes/<THEME>/layouts/section/baseof.html`
Squashed 'docs/' changes from f887bd7b..1d052b16 1d052b16 Update hosting-on-netlify.md 28b96bec Remove double brackets in Netlify hosting tutorial 373ed38b Update deployment instructions from hugo > 0.20 on Netlify 1bbb41ca Generate static assets on deploy in Nanobox tutorial 816d207f Add missing backtick in templates/views.md bf88e772 Add nanobox as a deployment option 9c37b4cc Change config's syntax order matching description d3cb05a7 Fix wrongly named default value of publishDir 4be85c54 Add link to showcase a theme setup via config file 46837195 Init and update of submodules in .gitlab-ci.yml 9e7c2827 Add CSS lang argument to code block 85aad56e Abstract the type in the lookup order 4e1e43e9 Fix broken Pygments url 65b4e79b Correct GitLab project pipelines URL 94af72b5 Fix .Data.Terms usage in taxonomy template example eb371e52 functions: Fix lang.NumFmt docs a745cd6c Fix layouts' folder name in template primer e181e637 Correct typo on GitHub pages guide (#151) 28698500 Remove HTML special chars from Windows install example 96b1f5b5 Remove not needed escape slashes in urls.md 2e05043f Add upgrade instructions using homebrew 2a14624d Fix alias in countrunes.md 5e26bb97 Update docker image for build/publish 01424887 List the internal templates a3ef5be9 Remove string concatenation from add (math) sample 43d12b44 Fix typo 89bafa49 Change to Asciidoc URI 4e14071e Removes an extra bracket (>) in single-page-templates.md 0938e423 Fix typo in http2 server push blog fac55121 Fix typo in deployment with rsync tutorial git-subtree-dir: docs git-subtree-split: 1d052b16a1290ada12f1e28c7c0c373f86741071
2017-09-05 16:09:40 +00:00
7. `/layouts/_default/<TYPE>-baseof.html`
8. `/themes/<THEME>/layouts/_default/<TYPE>-baseof.html`
9. `/layouts/_default/baseof.html`
10. `/themes/<THEME>/layouts/_default/baseof.html`
Variables are denoted by capitalized text set within `<>`. Note that Hugo's default behavior is for `type` to inherit from `section` unless otherwise specified.
### Example Base Template Lookup Order
As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `post` section. Hugo picks `layout/section/post.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template.
Here is the lookup order for the `post` base template:
1. `/layouts/section/post-baseof.html`
2. `/themes/mytheme/layouts/section/post-baseof.html`
3. `/layouts/post/baseof.html`
4. `/themes/mytheme/layouts/post/baseof.html`
5. `/layouts/section/baseof.html`
6. `/themes/mytheme/layouts/section/baseof.html`
7. `/layouts/_default/post-baseof.html`
8. `/themes/mytheme/layouts/_default/post-baseof.html`
9. `/layouts/_default/baseof.html`
10. `/themes/mytheme/layouts/_default/baseof.html`
## Define the Base Template
The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order.
{{< code file="layouts/_default/baseof.html" download="baseof.html" >}}
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>{{ block "title" . }}
<!-- Blocks may include default content. -->
{{ .Site.Title }}
{{ end }}</title>
</head>
<body>
<!-- Code that all your templates share, like a header -->
{{ block "main" . }}
<!-- The part of the page that begins to differ between templates -->
{{ end }}
{{ block "footer" . }}
<!-- More shared code, perhaps a footer but that can be overridden if need be in -->
{{ end }}
</body>
</html>
{{< /code >}}
## Override the Base Template
From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
{{< code file="layouts/_default/list.html" download="list.html" >}}
{{ define "main" }}
<h1>Posts</h1>
{{ range .Data.Pages }}
<article>
<h2>{{ .Title }}</h2>
{{ .Content }}
</article>
{{ end }}
{{ end }}
{{< /code >}}
This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists.
{{% warning %}}
Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example:
```
<!-- Seemingly harmless HTML comment..that will break your layout at build -->
{{ define "main" }}
...your code here
{{ end }}
```
[See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6)
{{% /warning %}}
The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]:
{{< code file="layouts/_default/single.html" download="single.html" >}}
{{ define "title" }}
<!-- This will override the default value set in baseof.html; i.e., "{{.Site.Title}}" in the original example-->
{{ .Title }} &ndash; {{ .Site.Title }}
{{ end }}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ end }}
{{< /code >}}
[hugolists]: /templates/lists
[lookup]: /templates/lookup-order/
[rendering the section]: /templates/section-templates/
[singletemplate]: /templates/single-page-templates/