Debian Codegraph @

docs/content/en/methods/site/Taxonomies.md

raw
1 ---
2 title: Taxonomies
3 description: 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.
4 categories: []
5 keywords: []
6 params:
7 functions_and_methods:
8 returnType: page.TaxonomyList
9 signatures: [SITE.Taxonomies]
10 ---
11
12 Conceptually, the `Taxonomies` method on a `Site` object returns a data structure such as:
13
14 <!-- markdownlint-disable MD007 MD032 -->
15 {{< code-toggle file=hugo >}}
16 taxonomy a:
17 - term 1:
18 - page 1
19 - page 2
20 - term 2:
21 - page 1
22 taxonomy b:
23 - term 1:
24 - page 2
25 - term 2:
26 - page 1
27 - page 2
28 {{< /code-toggle >}}
29 <!-- markdownlint-enable MD007 MD032 -->
30
31 For example, on a book review site you might create two taxonomies; one for genres and another for authors.
32
33 With this project configuration:
34
35 {{< code-toggle file=hugo >}}
36 [taxonomies]
37 genre = 'genres'
38 author = 'authors'
39 {{< /code-toggle >}}
40
41 And this content structure:
42
43 ```text
44 content/
45 ├── books/
46 │ ├── and-then-there-were-none.md --> genres: suspense
47 │ ├── death-on-the-nile.md --> genres: suspense
48 │ └── jamaica-inn.md --> genres: suspense, romance
49 │ └── pride-and-prejudice.md --> genres: romance
50 └── _index.md
51 ```
52
53 Conceptually, the taxonomies data structure looks like:
54
55 <!-- markdownlint-disable MD007 MD032 -->
56 {{< code-toggle file=hugo >}}
57 genres:
58 - suspense:
59 - And Then There Were None
60 - Death on the Nile
61 - Jamaica Inn
62 - romance:
63 - Jamaica Inn
64 - Pride and Prejudice
65 authors:
66 - achristie:
67 - And Then There Were None
68 - Death on the Nile
69 - ddmaurier:
70 - Jamaica Inn
71 - jausten:
72 - Pride and Prejudice
73 {{< /code-toggle >}}
74 <!-- markdownlint-enable MD007 MD032 -->
75
76 To list the "suspense" books:
77
78 ```go-html-template
79 <ul>
80 {{ range .Site.Taxonomies.genres.suspense }}
81 <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
82 {{ end }}
83 </ul>
84 ```
85
86 Hugo renders this to:
87
88 ```html
89 <ul>
90 <li><a href="/books/and-then-there-were-none/">And Then There Were None</a></li>
91 <li><a href="/books/death-on-the-nile/">Death on the Nile</a></li>
92 <li><a href="/books/jamaica-inn/">Jamaica Inn</a></li>
93 </ul>
94 ```
95
96 > [!note]
97 > Hugo's taxonomy system is powerful, allowing you to classify content and create relationships between pages.
98 >
99 > Please see the [taxonomies] section for a complete explanation and examples.
100
101 ## Examples
102
103 ### List content with the same taxonomy term
104
105 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:
106
107 ```go-html-template
108 <ul>
109 {{ range .Site.Taxonomies.series.golang }}
110 <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
111 {{ end }}
112 </ul>
113 ```
114
115 ### List all content in a given taxonomy
116
117 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.
118
119 ```go-html-template
120 <section id="menu">
121 <ul>
122 {{ range $term, $taxonomy := .Site.Taxonomies.featured }}
123 <li>{{ $term }}</li>
124 <ul>
125 {{ range $taxonomy.Pages }}
126 <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
127 {{ end }}
128 </ul>
129 {{ end }}
130 </ul>
131 </section>
132 ```
133
134 ### Render a site's taxonomies
135
136 The following example displays all terms in a site's tags taxonomy:
137
138 ```go-html-template
139 <ul>
140 {{ range .Site.Taxonomies.tags }}
141 <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
142 {{ end }}
143 </ul>
144 ```
145
146 This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
147
148 ```go-html-template {file="layouts/_partials/all-taxonomies.html"}
149 {{ with .Site.Taxonomies }}
150 {{ $numberOfTerms := 0 }}
151 {{ range $taxonomy, $terms := . }}
152 {{ $numberOfTerms = len . | add $numberOfTerms }}
153 {{ end }}
154
155 {{ if gt $numberOfTerms 0 }}
156 <ul>
157 {{ range $taxonomy, $terms := . }}
158 {{ with $terms }}
159 <li>
160 <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
161 <ul>
162 {{ range $term, $weightedPages := . }}
163 <li>
164 <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
165 <ul>
166 {{ range $weightedPages }}
167 <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
168 {{ end }}
169 </ul>
170 </li>
171 {{ end }}
172 </ul>
173 </li>
174 {{ end }}
175 {{ end }}
176 </ul>
177 {{ end }}
178 {{ end }}
179 ```
180
181 [taxonomies]: /content-management/taxonomies/