1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
---
title: Taxonomy templates
description: Create a taxonomy template to render a list of terms.
categories: []
keywords: []
weight: 80
aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy-templates/]
---
The [taxonomy](g) template below inherits the site's shell from the [base template], and renders a list of [terms](g) in the current taxonomy.
[base template]: /templates/types/
```go-html-template {file="layouts/_default/taxonomy.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.
[template lookup order]: /templates/lookup-order/#taxonomy-templates
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.
```go-html-template
{{ .Data.Singular }} → tag
```
Plural
: (`string`) Returns the plural name of the taxonomy.
```go-html-template
{{ .Data.Plural }} → tags
```
Terms
: (`page.Taxonomy`) Returns the `Taxonomy` object, consisting of a map of terms and the [weighted pages](g) associated with each term.
```go-html-template
{{ $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.
[methods]: /methods/taxonomy/
## 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.
```go-html-template {file="layouts/_default/taxonomy.html"}
{{ 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.
```go-html-template {file="layouts/_default/taxonomy.html"}
{{ 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](g), so we can also list the content to which each term is assigned.
[`Alphabetical`]: /methods/taxonomy/alphabetical/
[`ByCount`]: /methods/taxonomy/bycount/
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.
```go-html-template {file="layouts/_default/taxonomy.html"}
{{ 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:
{{< code-toggle file=hugo >}}
[taxonomies]
author = 'authors'
{{< /code-toggle >}}
Then create content with one [branch bundle](g) for each term:
```text
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:
```go-html-template {file="layouts/authors/taxonomy.html"}
{{ 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.
|
