Ryan Watters
4.4 KiB
title, linktitle, description, godocref, date, publishdate, lastmod, categories, tags, weight, draft, aliases, toc, wip
| title | linktitle | description | godocref | date | publishdate | lastmod | categories | tags | weight | draft | aliases | toc | wip | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Base Templates and Blocks | The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page) in a syntax that allows for easy extending and overwriting. | https://golang.org/pkg/text/template/#example_Template_block | 2017-02-01 | 2017-02-01 | 2017-02-01 |
|
|
20 | false |
|
true | true |
Go 1.6 includes a powerful new keyword, block. This construct allows you to define the outer shell of your pages one or more master template(s), filling in or overriding portions as necessary.
Base Template Lookup Order
This is the order Hugo searches for a base template:
/layouts/<CURRENTPATH>/<TEMPLATENAME>-baseof.html/layouts/<CURRENTPATH>/baseof.html/layouts/_default/<TEMPLATENAME>-baseof.html/layouts/_default/baseof.html
As an example, with a site using the theme exampletheme, when rendering the section list for the section post. Hugo picks the section/post.html as the template and this template has a define section that indicates it needs a base template. This is then the lookup order:
/layouts/section/post-baseof.html/themes/<THEME>/layouts/section/post-baseof.html/layouts/section/baseof.html/themes/<THEME>/layouts/section/baseof.html/layouts/_default/post-baseof.html/themes/<THEME>/layouts/_default/post-baseof.html/layouts/_default/baseof.html/themes/<THEME>/layouts/_default/baseof.html
Defining 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 our pages will start unless a more specific *baseof.html is defined.
{{% 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 }}
<!-- More shared code, perhaps a footer -->
</body>
</html>
{{% /code %}}
Overriding the Base Template
From the above base template, you can define a default list template. 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 %}}
{{% note "No Go Context "Dot" in Block Definitions" %}}
When using the define keyword, you do not need to use Go templates context reference (i.e., 'The Dot"). (Read more on "The Dot" in the Go Template Primer.)
{{% /note %}}
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:
<!-- Harmless comment..that will break your layout at build -->
{{ define "main" }}
...your code here
{{ end }}
See this thread from the Hugo discussion forums. {{% /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:
{{% 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 }} – {{ .Site.Title }}
{{ end }}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ end }}
{{% /code %}}