Taxonomies

Returns a data structure containing the site’s Taxonomy objects, the terms within each Taxonomy object, and the pages to which the terms are assigned.

Syntax

SITE.Taxonomies

Returns

page.TaxonomyList

Conceptually, the Taxonomies method on a Site object returns a data structure such as:

taxonomy a:
- term 1:
  - page 1
  - page 2
- term 2:
  - page 1
taxonomy b:
- term 1:
  - page 2
- term 2:
  - page 1
  - page 2

[['taxonomy a']]
  'term 1' = ['page 1', 'page 2']
[['taxonomy a']]
  'term 2' = ['page 1']
[['taxonomy b']]
  'term 1' = ['page 2']
[['taxonomy b']]
  'term 2' = ['page 1', 'page 2']

{
   "taxonomy a": [
      {
         "term 1": [
            "page 1",
            "page 2"
         ]
      },
      {
         "term 2": [
            "page 1"
         ]
      }
   ],
   "taxonomy b": [
      {
         "term 1": [
            "page 2"
         ]
      },
      {
         "term 2": [
            "page 1",
            "page 2"
         ]
      }
   ]
}

For example, on a book review site you might create two taxonomies; one for genres and another for authors.

With this site configuration:

taxonomies:
  author: authors
  genre: genres

[taxonomies]
  author = 'authors'
  genre = 'genres'

{
   "taxonomies": {
      "author": "authors",
      "genre": "genres"
   }
}

And this content structure:

content/
├── books/
│   ├── and-then-there-were-none.md --> genres: suspense
│   ├── death-on-the-nile.md        --> genres: suspense
│   └── jamaica-inn.md              --> genres: suspense, romance
│   └── pride-and-prejudice.md      --> genres: romance
└── _index.md

Conceptually, the taxonomies data structure looks like:

authors:
- achristie:
  - And Then There Were None
  - Death on the Nile
- ddmaurier:
  - Jamaica Inn
- jausten:
  - Pride and Prejudice
genres:
- suspense:
  - And Then There Were None
  - Death on the Nile
  - Jamaica Inn
- romance:
  - Jamaica Inn
  - Pride and Prejudice

[[authors]]
  achristie = ['And Then There Were None', 'Death on the Nile']
[[authors]]
  ddmaurier = ['Jamaica Inn']
[[authors]]
  jausten = ['Pride and Prejudice']
[[genres]]
  suspense = ['And Then There Were None', 'Death on the Nile', 'Jamaica Inn']
[[genres]]
  romance = ['Jamaica Inn', 'Pride and Prejudice']

{
   "authors": [
      {
         "achristie": [
            "And Then There Were None",
            "Death on the Nile"
         ]
      },
      {
         "ddmaurier": [
            "Jamaica Inn"
         ]
      },
      {
         "jausten": [
            "Pride and Prejudice"
         ]
      }
   ],
   "genres": [
      {
         "suspense": [
            "And Then There Were None",
            "Death on the Nile",
            "Jamaica Inn"
         ]
      },
      {
         "romance": [
            "Jamaica Inn",
            "Pride and Prejudice"
         ]
      }
   ]
}

To list the “suspense” books:

<ul>
  {{ range .Site.Taxonomies.genres.suspense }}
    <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
  {{ end }}
</ul>

Hugo renders this to:

<ul>
  <li><a href="/books/and-then-there-were-none/">And Then There Were None</a></li>
  <li><a href="/books/death-on-the-nile/">Death on the Nile</a></li>
  <li><a href="/books/jamaica-inn/">Jamaica Inn</a></li>
</ul>

Hugo’s taxonomy system is powerful, allowing you to classify content and create relationships between pages.

Please see the taxonomies section for a complete explanation and examples.

Examples

List content with the same taxonomy term

If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same term. For example:

<ul>
  {{ range .Site.Taxonomies.series.golang }}
    <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
  {{ end }}
</ul>

List all content in a given taxonomy

This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content.

<section id="menu">
  <ul>
    {{ range $term, $taxonomy := .Site.Taxonomies.featured }}
      <li>{{ $term }}</li>
      <ul>
        {{ range $taxonomy.Pages }}
          <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
        {{ end }}
      </ul>
    {{ end }}
  </ul>
</section>

Render a site’s taxonomies

The following example displays all terms in a site’s tags taxonomy:

<ul>
  {{ range .Site.Taxonomies.tags }}
    <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
  {{ end }}
</ul>

This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.

layouts/partials/all-taxonomies.html

{{ with .Site.Taxonomies }}
  {{ $numberOfTerms := 0 }}
  {{ range $taxonomy, $terms := . }}
    {{ $numberOfTerms = len . | add $numberOfTerms }}
  {{ end }}

  {{ if gt $numberOfTerms 0 }}
    <ul>
      {{ range $taxonomy, $terms := . }}
        {{ with $terms }}
          <li>
            <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
            <ul>
              {{ range $term, $weightedPages := . }}
                <li>
                  <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
                  <ul>
                    {{ range $weightedPages }}
                      <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
                    {{ end }}
                  </ul>
                </li>
              {{ end }}
            </ul>
          </li>
        {{ end }}
      {{ end }}
    </ul>
  {{ end }}
{{ end }}

Last updated: February 17, 2025 : all: Change shortcode usage and design to prevent invalid HTML (0fca8ef25)

Improve this page