taxonomy-templates.md (12556B)
1 ---
2 title: Taxonomy Templates
3 # linktitle:
4 description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates.
5 date: 2017-02-01
6 publishdate: 2017-02-01
7 lastmod: 2017-02-01
8 categories: [templates]
9 keywords: [taxonomies,metadata,front matter,terms,templates]
10 menu:
11 docs:
12 parent: "templates"
13 weight: 50
14 weight: 50
15 sections_weight: 50
16 draft: false
17 aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/]
18 toc: true
19 ---
20
21 <!-- NOTE! Check on https://github.com/gohugoio/hugo/issues/2826 for shifting of terms' pages to .Data.Pages AND
22 https://discourse.gohugo.io/t/how-to-specify-category-slug/4856/15 for original discussion.-->
23
24 Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies under Content Management](/content-management/taxonomies) if you are unfamiliar with how Hugo leverages this powerful feature.
25
26 Hugo provides multiple ways to use taxonomies throughout your project templates:
27
28 * Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-templates)
29 * Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-templates)
30 * List a single content's taxonomy terms within a [single page template][]
31
32 ## Taxonomy List Templates
33
34 Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists].
35
36 ### Taxonomy List Template Lookup Order
37
38 See [Template Lookup](/templates/lookup-order/).
39
40 ## Taxonomy Terms Templates
41
42 ### Taxonomy Terms Templates Lookup Order
43
44 See [Template Lookup](/templates/lookup-order/).
45
46 ### Taxonomy Methods
47
48 A Taxonomy is a `map[string]WeightedPages`.
49
50 .Get(term)
51 : Returns the WeightedPages for a term.
52
53 .Count(term)
54 : The number of pieces of content assigned to this term.
55
56 .Alphabetical
57 : Returns an OrderedTaxonomy (slice) ordered by Term.
58
59 .ByCount
60 : Returns an OrderedTaxonomy (slice) ordered by number of entries.
61
62 .Reverse
63 : Returns an OrderedTaxonomy (slice) in reverse order. Must be used with an OrderedTaxonomy.
64
65 ### OrderedTaxonomy
66
67 Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order.
68
69 ```go
70 []struct {
71 Name string
72 WeightedPages WeightedPages
73 }
74 ```
75
76 Each element of the slice has:
77
78 .Term
79 : The Term used.
80
81 .WeightedPages
82 : A slice of Weighted Pages.
83
84 .Count
85 : The number of pieces of content assigned to this term.
86
87 .Pages
88 : All Pages assigned to this term. All [list methods][renderlists] are available to this.
89
90 ## WeightedPages
91
92 WeightedPages is simply a slice of WeightedPage.
93
94 ```go
95 type WeightedPages []WeightedPage
96 ```
97
98 .Count(term)
99 : The number of pieces of content assigned to this term.
100
101 .Pages
102 : Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists].
103
104 ## Displaying custom metadata in Taxonomy Terms Templates
105
106 If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-metadata-to-a-taxonomy-or-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Pages` as such:
107
108 ```go-html-template
109 <ul>
110 {{ range .Pages }}
111 <li>
112 <a href="{{ .Permalink }}">{{ .Title }}</a>
113 {{ .Params.wikipedia }}
114 </li>
115 {{ end }}
116 </ul>
117 ```
118
119 <!-- Begin /taxonomies/ordering/ -->
120
121 ## Order Taxonomies
122
123 Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key.
124
125 ### Order Alphabetically Example
126
127 ```go-html-template
128 <ul>
129 {{ range .Data.Terms.Alphabetical }}
130 <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
131 {{ end }}
132 </ul>
133 ```
134
135 <!-- [See Also Taxonomy Lists](/templates/list/) -->
136
137 ## Order Content within Taxonomies
138
139 Hugo uses both `date` and `weight` to order content within taxonomies.
140
141 Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to.
142
143 When iterating over content within taxonomies, the default sort is the same as that used for section and list pages: first by weight, then by date. This means that if the weights for two pieces of content are the same, then the more recent content will be displayed first.
144
145 The default weight for any piece of content is 0. Zero means "does not have a weight", not "has a weight of numerical value zero".
146
147 Weights of zero are thus treated specially: if two pages have unequal weights, and one of them is zero, then the zero-weighted page will always appear after the other one, regardless of the other's weight. Zero weights should thus be used with care: for example, if both positive and negative weights are used to extend a sequence in both directions, a zero-weighted page will appear not in the middle of the list, but at the end.
148
149 ### Assign Weight
150
151 Content can be assigned weight for each taxonomy that it's assigned to.
152
153 ```
154 +++
155 tags = [ "a", "b", "c" ]
156 tags_weight = 22
157 categories = ["d"]
158 title = "foo"
159 categories_weight = 44
160 +++
161 Front Matter with weighted tags and categories
162 ```
163
164 The convention is `taxonomyname_weight`.
165
166 In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy.
167
168 It has also been assigned the weight of 44 when rendering the 'd' category.
169
170 With this the same piece of content can appear in different positions in different taxonomies.
171
172 Currently taxonomies only support the default ordering of content which is weight -> date.
173
174 <!-- Begin /taxonomies/templates/ -->
175
176 There are two different templates that the use of taxonomies will require you to provide.
177
178 Both templates are covered in detail in the templates section.
179
180 A [list template](/templates/list/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages.
181
182 A [taxonomy terms template](/templates/terms/) is a template used to
183 generate the list of terms for a given template.
184
185 <!-- Begin /taxonomies/displaying/ -->
186
187 There are four common ways you can display the data in your
188 taxonomies in addition to the automatic taxonomy pages created by hugo
189 using the [list templates](/templates/list/):
190
191 1. For a given piece of content, you can list the terms attached
192 2. For a given piece of content, you can list other content with the same
193 term
194 3. You can list all terms for a taxonomy
195 4. You can list all taxonomies (with their terms)
196
197 ## Display a Single Piece of Content's Taxonomies
198
199 Within your content templates, you may wish to display the taxonomies that piece of content is assigned to.
200
201 Because we are leveraging the front matter system to define taxonomies for content, the taxonomies assigned to each content piece are located in the usual place (i.e., `.Params.<TAXONOMYPLURAL>`).
202
203 ### Example: List Tags in a Single Page Template
204
205 ```go-html-template
206 <ul>
207 {{ range (.GetTerms "tags") }}
208 <li><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li>
209 {{ end }}
210 </ul>
211 ```
212
213 If you want to list taxonomies inline, you will have to take care of optional plural endings in the title (if multiple taxonomies), as well as commas. Let's say we have a taxonomy "directors" such as `directors: [ "Joel Coen", "Ethan Coen" ]` in the TOML-format front matter.
214
215 To list such taxonomies, use the following:
216
217 ### Example: Comma-delimit Tags in a Single Page Template
218
219 ```go-html-template
220 {{ $taxo := "directors" }} <!-- Use the plural form here -->
221 {{ with .Param $taxo }}
222 <strong>Director{{ if gt (len .) 1 }}s{{ end }}:</strong>
223 {{ range $index, $director := . }}
224 {{- if gt $index 0 }}, {{ end -}}
225 {{ with $.Site.GetPage (printf "/%s/%s" $taxo $director) -}}
226 <a href="{{ .Permalink }}">{{ $director }}</a>
227 {{- end -}}
228 {{- end -}}
229 {{ end }}
230 ```
231
232 Alternatively, you may use the [delimit template function][delimit] as a shortcut if the taxonomies should just be listed with a separator. See {{< gh 2143 >}} on GitHub for discussion.
233
234 ## List Content with the Same Taxonomy Term
235
236 If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content:
237
238 ### Example: Showing Content in Same Series
239
240 ```go-html-template
241 <ul>
242 {{ range .Site.Taxonomies.series.golang }}
243 <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
244 {{ end }}
245 </ul>
246 ```
247
248 ## List All content in a Given taxonomy
249
250 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.
251
252 ### Example: Grouping "Featured" Content
253
254 ```go-html-template
255 <section id="menu">
256 <ul>
257 {{ range $key, $taxonomy := .Site.Taxonomies.featured }}
258 <li>{{ $key }}</li>
259 <ul>
260 {{ range $taxonomy.Pages }}
261 <li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}">{{ .LinkTitle }}</a></li>
262 {{ end }}
263 </ul>
264 {{ end }}
265 </ul>
266 </section>
267 ```
268
269 ## Render a Site's Taxonomies
270
271 If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page.
272
273 This may take the form of a tag cloud, a menu, or simply a list.
274
275 The following example displays all terms in a site's tags taxonomy:
276
277 ### Example: List All Site Tags {#example-list-all-site-tags}
278
279 ```go-html-template
280 <ul>
281 {{ range .Site.Taxonomies.tags }}
282 <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
283 {{ end }}
284 </ul>
285 ```
286
287 ### Example: List All Taxonomies, Terms, and Assigned Content
288
289 This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
290
291 {{< code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" >}}
292 <section>
293 <ul id="all-taxonomies">
294 {{ range $taxonomy_term, $taxonomy := .Site.Taxonomies }}
295 {{ with $.Site.GetPage (printf "/%s" $taxonomy_term) }}
296 <li><a href="{{ .Permalink }}">{{ $taxonomy_term }}</a>
297 <ul>
298 {{ range $key, $value := $taxonomy }}
299 <li>{{ $key }}</li>
300 <ul>
301 {{ range $value.Pages }}
302 <li hugo-nav="{{ .RelPermalink}}">
303 <a href="{{ .Permalink}}">{{ .LinkTitle }}</a>
304 </li>
305 {{ end }}
306 </ul>
307 {{ end }}
308 </ul>
309 </li>
310 {{ end }}
311 {{ end }}
312 </ul>
313 </section>
314 {{< /code >}}
315
316 ## `.Site.GetPage` for Taxonomies
317
318 Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the ["List All Site Tags" example above]({{< relref "#example-list-all-site-tags" >}}):
319
320 {{< code file="links-to-all-tags.html" >}}
321 {{ $taxo := "tags" }}
322 <ul class="{{ $taxo }}">
323 {{ with ($.Site.GetPage (printf "/%s" $taxo)) }}
324 {{ range .Pages }}
325 <li><a href="{{ .Permalink }}">{{ .Title}}</a></li>
326 {{ end }}
327 {{ end }}
328 </ul>
329 {{< /code >}}
330
331 <!-- TODO: ### `.Site.GetPage` Taxonomy List Example -->
332
333 <!-- TODO: ### `.Site.GetPage` Taxonomy Terms Example -->
334
335
336 [delimit]: /functions/delimit/
337 [getpage]: /functions/getpage/
338 [lists]: /templates/lists/
339 [renderlists]: /templates/lists/
340 [single page template]: /templates/single-page-templates/
341 [sitevars]: /variables/site/