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
165
166
167
168
169
170
171
172
173
174
175
176
|
---
title: Taxonomy templates
description: Create a taxonomy template to render a list of terms.
categories: [templates]
keywords: []
menu:
docs:
parent: templates
weight: 90
weight: 90
toc: true
aliases: [/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.
[taxonomy]: /getting-started/glossary/#taxonomy
[terms]: /getting-started/glossary/#term
[base template]: /templates/types/
{{< code file=layouts/_default/taxonomy.html >}}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ end }}
{{< /code >}}
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] associated with each term.
[weighted pages]: /getting-started/glossary/#weighted-page
```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.
{{< code 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 }}
{{< /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" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ range .Data.Terms.ByCount }}
<h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
{{ 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.
[ordered taxonomy]: /getting-started/glossary/#ordered-taxonomy
[`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.
{{< code 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 }}
{{< /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:
[branch bundle]: /getting-started/glossary/#branch-bundle
```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:
{{< code 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 }}
{{< /code >}}
In the example above we list each author including their affiliation and portrait.
|
