Taxonomy templates

The [taxonomy] template below inherits the site’s shell from the [base template], and renders a list of [terms] in the current taxonomy.

{{ 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 taxonomy and term will be capitalized if their respective pages are not backed by files. 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 taxonomy 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

Terms

(page.Taxonomy) Returns the Taxonomy object, consisting of a map of terms and the [weighted pages] associated with each term.

{{ $taxonomyObject := .Data.Terms }} 

Once we have the Taxonomy object, we can call any of its [methods], allowing us to sort alphabetically or by term count.

Sort alphabetically #

The taxonomy template below inherits the site’s shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list alphabetically by term, and displays the number of pages associated with each term.

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
  {{ range .Data.Terms.Alphabetical }}
    <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
  {{ end }}
{{ end }}

Sort by term count #

The taxonomy template below inherits the site’s shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list by the number of pages associated with each term, and displays the number of pages associated with each term.

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
  {{ range .Data.Terms.ByCount }}
    <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
  {{ end }}
{{ end }}

Include content links #

The [Alphabetical] and [ByCount] methods used in the previous examples return an [ordered taxonomy], so we can also list the content to which each term is assigned.

The taxonomy template below inherits the site’s shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list by the number of pages associated with each term, displays the number of pages associated with each term, then lists the content to which each term is assigned.

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
  {{ range .Data.Terms.ByCount }}
    <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
    <ul>
      {{ range .WeightedPages }}
        <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
      {{ end }}
    </ul>
  {{ end }}
{{ end }}

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 taxonomy template specific to the “authors” taxonomy:

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
  {{ range .Data.Terms.Alphabetical }}
    <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a></h2>
    <p>Affiliation: {{ .Page.Params.Affiliation }}</p>
    {{ with .Page.Resources.Get "portrait.jpg" }}
      {{ with .Fill "100x100" }}
        <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="portrait">
      {{ end }}
    {{ end }}
  {{ end }}
{{ end }}

In the example above we list each author including their affiliation and portrait.