taxonomies.md (9051B)
1 ---
2 title: Taxonomies
3 linktitle:
4 description: Hugo includes support for user-defined taxonomies.
5 date: 2017-02-01
6 publishdate: 2017-02-01
7 keywords: [taxonomies,metadata,front matter,terms]
8 categories: [content management]
9 menu:
10 docs:
11 parent: "content-management"
12 weight: 80
13 weight: 80 #rem
14 draft: false
15 aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes]
16 toc: true
17 ---
18
19 ## What is a Taxonomy?
20
21 Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications of logical relationships between content.
22
23 ### Definitions
24
25 Taxonomy
26 : a categorization that can be used to classify content
27
28 Term
29 : a key within the taxonomy
30
31 Value
32 : a piece of content assigned to a term
33
34
35 ## Example Taxonomy: Movie Website
36
37 Let's assume you are making a website about movies. You may want to include the following taxonomies:
38
39 * Actors
40 * Directors
41 * Studios
42 * Genre
43 * Year
44 * Awards
45
46 Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the [front matter][] of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.
47
48 ### Movie Taxonomy Organization
49
50 To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy:
51
52 ```
53 Actor <- Taxonomy
54 Bruce Willis <- Term
55 The Sixth Sense <- Value
56 Unbreakable <- Value
57 Moonrise Kingdom <- Value
58 Samuel L. Jackson <- Term
59 Unbreakable <- Value
60 The Avengers <- Value
61 xXx <- Value
62 ```
63
64 From the perspective of the content, the relationships would appear differently, although the data and labels used are the same:
65
66 ```
67 Unbreakable <- Value
68 Actors <- Taxonomy
69 Bruce Willis <- Term
70 Samuel L. Jackson <- Term
71 Director <- Taxonomy
72 M. Night Shyamalan <- Term
73 ...
74 Moonrise Kingdom <- Value
75 Actors <- Taxonomy
76 Bruce Willis <- Term
77 Bill Murray <- Term
78 Director <- Taxonomy
79 Wes Anderson <- Term
80 ...
81 ```
82
83 ## Hugo Taxonomy Defaults {#default-taxonomies}
84
85 Hugo natively supports taxonomies.
86
87 Without adding a single line to your [site config][config] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be the same as manually [configuring your taxonomies](#configure-taxonomies) as below:
88
89 {{< code-toggle copy="false" >}}
90 [taxonomies]
91 tag = "tags"
92 category = "categories"
93 {{</ code-toggle >}}
94
95 If you do not want Hugo to create any taxonomies, set `disableKinds` in your [site config][config] to the following:
96
97 {{< code-toggle copy="false" >}}
98 disableKinds = ["taxonomy","term"]
99 {{</ code-toggle >}}
100
101 {{< new-in "0.73.0" >}} We have fixed the before confusing page kinds used for taxonomies (see the listing below) to be in line with the terms used when we talk about taxonomies. We have been careful to avoid site breakage, and you should get an ERROR in the console if you need to adjust your `disableKinds` section.
102
103 {{% page-kinds %}}
104
105 ### Default Destinations
106
107 When taxonomies are used---and [taxonomy templates][] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages:
108
109 * A single page at `example.com/categories/` that lists all the [terms within the taxonomy][]
110 * [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter][]
111
112 ## Configure Taxonomies
113
114 Custom taxonomies other than the [defaults](#default-taxonomies) must be defined in your [site config][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML.
115
116 ### Example: Adding a custom taxonomy named "series"
117
118 {{% note %}}
119 While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_.
120 {{% /note %}}
121
122 {{< code-toggle copy="false" >}}
123 [taxonomies]
124 tag = "tags"
125 category = "categories"
126 series = "series"
127 {{</ code-toggle >}}
128
129 ### Example: Removing default taxonomies
130
131 If you want to have just the default `tags` taxonomy, and remove the `categories` taxonomy for your site, you can do so by modifying the `taxonomies` value in your [site config][config].
132
133 {{< code-toggle copy="false" >}}
134 [taxonomies]
135 tag = "tags"
136 {{</ code-toggle >}}
137
138 If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies).
139
140 {{% note %}}
141 You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose.
142
143 Much like regular pages, taxonomy list [permalinks](/content-management/urls/) are configurable, but taxonomy term page permalinks are not.
144 {{% /note %}}
145
146 {{% warning %}}
147 The configuration option `preserveTaxonomyNames` was removed in Hugo 0.55.
148
149 You can now use `.Page.Title` on the relevant taxonomy node to get the original value.
150 {{% /warning %}}
151
152 ## Add Taxonomies to Content
153
154 Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type][] or [content section][].
155
156 Assigning content to a taxonomy is done in the [front matter][]. Simply create a variable with the *plural* name of the taxonomy and assign all terms you want to apply to the instance of the content type.
157
158 {{% note %}}
159 If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/).
160 {{% /note %}}
161
162 ### Example: Front Matter with Taxonomies
163
164 {{< code-toggle copy="false">}}
165 title = "Hugo: A fast and flexible static site generator"
166 tags = [ "Development", "Go", "fast", "Blogging" ]
167 categories = [ "Development" ]
168 series = [ "Go Web Dev" ]
169 slug = "hugo"
170 project_url = "https://github.com/gohugoio/hugo"
171 {{</ code-toggle >}}
172
173 ## Order Taxonomies
174
175 A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in [taxonomy list templates][] and is declared in a content file's [front matter][]. The convention for declaring taxonomic weight is `taxonomyname_weight`.
176
177 The following TOML and YAML examples show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page.
178
179 ### Example: Taxonomic `weight`
180
181 {{< code-toggle copy="false" >}}
182 title = "foo"
183 tags = [ "a", "b", "c" ]
184 tags_weight = 22
185 categories = ["d"]
186 categories_weight = 44
187 {{</ code-toggle >}}
188
189 By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies.
190
191 {{% note "Limits to Ordering Taxonomies" %}}
192 Currently taxonomies only support the [default `weight => date` ordering of list content](/templates/lists/#default-weight--date--linktitle--filepath). For more information, see the documentation on [taxonomy templates](/templates/taxonomy-templates/).
193 {{% /note %}}
194
195 ## Add custom metadata to a Taxonomy or Term
196
197 If you need to add custom metadata to your taxonomy terms, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in it's front matter. Continuing with our 'Actors' example, let's say you want to add a Wikipedia page link to each actor. Your terms pages would be something like this:
198
199 {{< code file="/content/actors/bruce-willis/_index.md" >}}
200 ---
201 title: "Bruce Willis"
202 wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
203 ---
204 {{< /code >}}
205
206
207 [`urlize` template function]: /functions/urlize/
208 [content section]: /content-management/sections/
209 [content type]: /content-management/types/
210 [documentation on archetypes]: /content-management/archetypes/
211 [front matter]: /content-management/front-matter/
212 [taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-list-templates
213 [taxonomy templates]: /templates/taxonomy-templates/
214 [terms within the taxonomy]: /templates/taxonomy-templates/#taxonomy-terms-templates "See how to order terms associated with a taxonomy"
215 [config]: /getting-started/configuration/