hugo/docs/content/en/templates/taxonomy.md

title	description	categories	keywords	menu	weight	toc	aliases
Taxonomy templates	Create a taxonomy template to render a list of terms.	templates		docs parent weight templates 90	90	true	/taxonomies/displaying/ /templates/terms/ /indexes/displaying/ /taxonomies/templates/ /indexes/ordering/ /templates/taxonomies/ /templates/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.

{{< code file=layouts/_default/taxonomy.html >}} {{ define "main" }}

{{ .Title }}

{{ .Content }} {{ range .Pages }}

{{ .LinkTitle }}

{{ end }} {{ end }} {{< /code >}}

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:

{{< code-toggle file=hugo >}} capitalizeListTitles = false {{< /code-toggle >}}

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.

{{< code file=layouts/_default/taxonomy.html >}} {{ define "main" }}

{{ .Title }}

{{ .Content }} {{ range .Data.Terms.Alphabetical }}

{{ .Page.LinkTitle }} ({{ .Count }})

{{ end }} {{ end }} {{< /code >}}

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.

{{< code file=layouts/_default/taxonomy.html >}} {{ define "main" }}

{{ .Title }}

{{ .Content }} {{ range .Data.Terms.ByCount }}

{{ .Page.LinkTitle }} ({{ .Count }})

{{ end }} {{ end }} {{< /code >}}

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.

{{< code file=layouts/_default/taxonomy.html >}} {{ define "main" }}

{{ .Title }}

{{ .Content }} {{ range .Data.Terms.ByCount }}

{{ .Page.LinkTitle }} ({{ .Count }})

{{ range .WeightedPages }}
• {{ .LinkTitle }}
{{ end }}

{{ end }} {{ end }} {{< /code >}}

Display metadata

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

For example, create an "authors" taxonomy:

{{< code-toggle file=hugo >}} [taxonomies] author = 'authors' {{< /code-toggle >}}

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:

{{< code-toggle file=content/authors/jsmith/_index.md fm=true >}} title = "John Smith" affiliation = "University of Chicago" {{< /code-toggle >}}

Then create a taxonomy template specific to the "authors" taxonomy:

{{< code file=layouts/authors/taxonomy.html >}} {{ define "main" }}

{{ .Title }}

{{ .Content }} {{ range .Data.Terms.Alphabetical }}

{{ .Page.LinkTitle }}

Affiliation: {{ .Page.Params.Affiliation }}

{{ with .Page.Resources.Get "portrait.jpg" }} {{ with .Fill "100x100" }} {{ end }} {{ end }} {{ end }} {{ end }} {{< /code >}}

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