Hugo - Block Templates

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

This is the order Hugo searches for a base template:

/layouts/current-path/template-name-baseof.html, e.g. list-baseof.html.
/layouts/current-path/baseof.html
/layouts/_default/template-name-baseof.html e.g. list-baseof.html.
/layouts/_default/baseof.html

For each of the steps above, it will first look in the project, then, if theme is set, in the theme’s layouts folder. Hugo picks the first base template found.

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/exampletheme/layouts/section/post-baseof.html
/layouts/section/baseof.html
/themes/exampletheme/layouts/section/baseof.html
/layouts/_default/post-baseof.html
/themes/exampletheme/layouts/_default/post-baseof.html
/layouts/_default/baseof.html
/themes/exampletheme/layouts/_default/baseof.html

Define the base template

Let’s define a simple base template (_default/baseof.html), a shell from which all our pages will start.

<!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>

Overriding the base

Your default list template (_default/list.html) will inherit all of the code defined in the base template. It could then implement its own “main” block from the base template above like so:

<!-- Note the lack of Go's context "dot" when defining blocks -->
{{ define "main" }}
  <h1>Posts</h1>
  {{ range .Data.Pages }}
    <article>
      <h2>{{ .Title }}</h2>
      {{ .Content }}
    </article>
  {{ end }}
{{ end }}

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.

In our default single template (_default/single.html), let’s implement both blocks:

{{ define "title" }}
  {{ .Title }} &ndash; {{ .Site.Title }}
{{ end }}
{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
{{ end }}

This overrides both block areas from the base template with code unique to our single template.