Taxonomies
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:
hugo.
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>
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 }}