HUGO
News Docs Themes Community GitHub

Term templates

Create a term template to render a list of pages associated with the current term.
We did a complete overhaul of Hugo’s template system in v0.146.0. We’re working on getting all of the relevant documentation up to date, but until then, see this page.

The term template below inherits the site’s shell from the base template, and renders a list of pages associated with the current term.

layouts/_default/term.html
{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
  {{ range .Pages }}
    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
  {{ end }}
{{ end }}

Review the template lookup order to select a template path that provides the desired level of specificity.

In the example above, the term will be capitalized if its respective page is not backed by a file. You can disable this in your site configuration:

capitalizeListTitles: false
capitalizeListTitles = false
{
   "capitalizeListTitles": false
}

Data object

Use these methods on the Data object within a term template.

Singular
(string) Returns the singular name of the taxonomy.
{{ .Data.Singular }} → tag
Plural
(string) Returns the plural name of the taxonomy.
{{ .Data.Plural }} → tags
Term
(string) Returns the name of the term.
{{ .Data.Term }} → fiction

Display metadata

Display metadata about each term by creating a corresponding branch bundle in the content directory.

For example, create an “authors” taxonomy:

taxonomies:
  author: authors
[taxonomies]
  author = 'authors'
{
   "taxonomies": {
      "author": "authors"
   }
}

Then create content with one branch bundle for each term:

content/
└── authors/
    ├── jsmith/
    │   ├── _index.md
    │   └── portrait.jpg
    └── rjones/
        ├── _index.md
        └── portrait.jpg

Then add front matter to each term page:

---
affiliation: University of Chicago
title: John Smith
---
+++
affiliation = 'University of Chicago'
title = 'John Smith'
+++
{
   "affiliation": "University of Chicago",
   "title": "John Smith"
}

Then create a term template specific to the “authors” taxonomy:

layouts/authors/term.html
{{ define "main" }}
  <h1>{{ .Title }}</h1>
  <p>Affiliation: {{ .Params.affiliation }}</p>
  {{ with .Resources.Get "portrait.jpg" }}
    {{ with .Fill "100x100" }}
      <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="portrait">
    {{ end }}
  {{ end }}
  {{ .Content }}
  {{ range .Pages }}
    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
  {{ end }}
{{ end }}

In the example above we display the author with their affiliation and portrait, then a list of associated content.