You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Structure the content using taxonomies like tags, categories, labels.
8
+
cSpell:ignore: taxo
9
9
---
10
10
11
-
Docsy supports Hugo's Taxonomies (see: https://gohugo.io/content-management/taxonomies/) in its docs and blog section. You can see the default layout and can test the behavior of the generated links on this page.
11
+
Docsy supports Hugo [taxonomies] in its docs and blog section. You can see the
12
+
default layout and can test the behavior of the generated links on this page.
12
13
13
14
## Terminology
14
15
15
-
To understand the usage of taxonomies you should understand the following terminology:
16
+
To understand the usage of taxonomies you should understand the following
17
+
terminology:
16
18
17
-
Taxonomy
18
-
: a categorization that can be used to classify content - e.g.: Tags, Categories, Projects, People
19
+
-**Taxonomy**: a categorization that can be used to classify content - e.g.:
20
+
Tags, Categories, Projects, People
19
21
20
-
Term
21
-
: a key within the taxonomy - e.g. within projects: Project A, Project B
22
+
-**Term**: a key within the taxonomy - e.g. within projects: Project A, Project
23
+
B
22
24
23
-
Value
24
-
: a piece of content assigned to a term - e.g. a page of your site, that belongs to a specific project
25
+
-**Value**: a piece of content assigned to a term - e.g. a page of your site,
26
+
that belongs to a specific project
25
27
26
-
A example taxonomy for a moviewebsite you can find in the official Hugo docs: https://gohugo.io/content-management/taxonomies/#example-taxonomy-movie-website
28
+
A [movie-website sample][] taxonomy is provided by the Hugo docs.
There are various parameter to control the functionality of taxonomies in the project [configuration file].
33
+
## Parameters
31
34
32
-
By default taxonomies for `tags` and `categories` are enabled in Hugo (see: https://gohugo.io/content-management/taxonomies/#default-destinations). In Docsy taxonomies can be __disabled__ in the `hugo.toml`/`hugo.yaml`/`hugo.json`:
35
+
There are various parameter to control the functionality of taxonomies in the
36
+
project [configuration file][]. Taxonomies are [enabled by default][] for `tags`
37
+
and `categories` in Hugo. To **disable** taxonomies, add the following to your
If you want to enable taxonomies in Docsy make sure you have deleted (or commented out) this line in your project's `hugo.toml`/`hugo.yaml`/`hugo.json`. Then the taxonomy pages for `tags` and `categories` will be generated by Hugo. If you want to use other taxonomies you have to define them in your [configuration file]. If you want to use beside your own taxonomies also the default taxonomies `tags` and `categories`, you also have to define them beside your own taxonomies. You need to provide both the plural and singular labels for each taxonomy.
57
+
Then the taxonomy pages for `tags` and `categories` will be generated by Hugo.
58
+
If you want to use other taxonomies you have to define them in your
59
+
[configuration file]. If you want to use beside your own taxonomies also the
60
+
default taxonomies `tags` and `categories`, you also have to define them beside
61
+
your own taxonomies. You need to provide both the plural and singular labels for
62
+
each taxonomy.
51
63
52
-
With the following example you define a additional taxonomy `projects` beside the default taxonomies `tags` and `categories`:
64
+
With the following example you define a additional taxonomy `projects` beside
You can use the following parameters in your project's `hugo.toml`/`hugo.yaml`/`hugo.json` to control the output of the assigned taxonomy terms for each article resp. page of your docs and/or blog section in Docsy or a "tag cloud" in Docsy's right sidebar:
94
+
You can use the following parameters in your project's config to control the
95
+
output of the assigned taxonomy terms for each article resp. page of your docs
96
+
and/or blog section in Docsy or a "tag cloud" in Docsy's right sidebar:
The settings above would only show a taxonomy cloud for `projects` and `tags`
144
+
(with the headlines "Our Projects" and "Tag Cloud") in Docsy's right sidebar and
145
+
the assigned terms for the taxonomies `tags` and `categories` for each page.
123
146
124
-
The settings above would only show a taxonomy cloud for `projects` and `tags` (with the headlines "Our Projects" and "Tag Cloud") in Docsy's right sidebar and the assigned terms for the taxonomies `tags` and `categories` for each page.
147
+
To disable any taxonomy cloud you have to set the Parameter `taxonomyCloud = []`
148
+
resp. if you don't want to show the assigned terms you have to set
149
+
`taxonomyPageHeader = []`.
125
150
126
-
To disable any taxonomy cloud you have to set the Parameter `taxonomyCloud = []` resp. if you don't want to show the assigned terms you have to set `taxonomyPageHeader = []`.
151
+
As default the plural label of a taxonomy is used as it cloud title. You can
152
+
overwrite the default cloud title with `taxonomyCloudTitle`. But if you do so,
153
+
you have to define a manual title for each enabled taxonomy cloud
154
+
(`taxonomyCloud` and `taxonomyCloudTitle` must have the same length!).
127
155
128
-
As default the plural label of a taxonomy is used as it cloud title. You can overwrite the default cloud title with `taxonomyCloudTitle`. But if you do so, you have to define a manual title for each enabled taxonomy cloud (`taxonomyCloud` and `taxonomyCloudTitle` must have the same length!).
156
+
If you don't set the parameters `taxonomyCloud` resp. `taxonomyPageHeader` the
157
+
taxonomy clouds resp. assigned terms for all defined taxonomies will be
158
+
generated.
129
159
130
-
If you don't set the parameters `taxonomyCloud` resp. `taxonomyPageHeader` the taxonomy clouds resp. assigned terms for all defined taxonomies will be generated.
131
160
## Partials
132
161
133
-
The by default used partials for displaying taxonomies are so defined, that you should be able to use them also easily in your own layouts.
162
+
The by default used partials for displaying taxonomies are so defined, that you
163
+
should be able to use them also easily in your own layouts.
134
164
135
165
### taxonomy_terms_article
136
166
137
-
The partial `taxonomy_terms_article` shows all assigned terms of an given taxonomy (partial parameter `taxo`) of an article respectively page (partial parameter `context`, most of the time the current page or context `.`).
167
+
The partial `taxonomy_terms_article` shows all assigned terms of an given
168
+
taxonomy (partial parameter `taxo`) of an article respectively page (partial
169
+
parameter `context`, most of the time the current page or context `.`).
138
170
139
-
Example usage in `layouts/docs/list.html` for the header of each page in the docs section:
171
+
Example usage in `layouts/docs/list.html` for the header of each page in the
172
+
docs section:
140
173
141
174
```go-html-template
142
175
{{ $context := . }}
@@ -145,33 +178,72 @@ Example usage in `layouts/docs/list.html` for the header of each page in the doc
145
178
{{ end }}
146
179
```
147
180
148
-
This will gave you for each in the current page (resp. context) defined taxonomy a list with all assigned terms:
181
+
This will gave you for each in the current page (resp. context) defined taxonomy
The partial `taxonomy_terms_article_wrapper` is a wrapper for the partial `taxonomy_terms_article` with the only parameter `context` (most of the time the current page or context `.`) and checks the taxonomy parameters of your project's `hugo.toml`/`hugo.yaml`/`hugo.json` to loop threw all listed taxonomies in the parameter `taxonomyPageHeader` resp. all defined taxonomies of your page, if `taxonomyPageHeader` isn't set.
231
+
The partial `taxonomy_terms_article_wrapper` is a wrapper for the partial
232
+
`taxonomy_terms_article` with the only parameter `context` (most of the time the
233
+
current page or context `.`) and checks the taxonomy parameters of your
234
+
project's `hugo.toml`/`hugo.yaml`/`hugo.json` to loop threw all listed
235
+
taxonomies in the parameter `taxonomyPageHeader` resp. all defined taxonomies of
236
+
your page, if `taxonomyPageHeader` isn't set.
169
237
170
238
### taxonomy_terms_cloud
171
239
172
-
The partial `taxonomy_terms_cloud` shows all used terms of an given taxonomy (partial parameter `taxo`) for your site (partial parameter `context`, most of the time the current page or context `.`) and with the parameter `title` as headline.
240
+
The partial `taxonomy_terms_cloud` shows all used terms of an given taxonomy
241
+
(partial parameter `taxo`) for your site (partial parameter `context`, most of
242
+
the time the current page or context `.`) and with the parameter `title` as
243
+
headline.
173
244
174
-
Example usage in partial `taxonomy_terms_clouds` for showing all defined taxonomies and its terms:
245
+
Example usage in partial `taxonomy_terms_clouds` for showing all defined
246
+
taxonomies and its terms:
175
247
176
248
```go-html-template
177
249
{{ $context := . }}
@@ -180,25 +252,69 @@ Example usage in partial `taxonomy_terms_clouds` for showing all defined taxonom
180
252
{{ end }}
181
253
```
182
254
183
-
As an example this will gave you for following HTML markup for the taxonomy `categories`:
255
+
This will give you the following HTML markup for the taxonomy `categories`:
The partial `taxonomy_terms_clouds` is a wrapper for the partial `taxonomy_terms_cloud` with the only parameter `context` (most of the time the current page or context `.`) and checks the taxonomy parameters of your project's `hugo.toml`/`hugo.yaml`/`hugo.json` to loop threw all listed taxonomies in the parameter `taxonomyCloud` resp. all defined taxonomies of your page, if `taxonomyCloud` isn't set.
303
+
The partial `taxonomy_terms_clouds` is a wrapper for the partial
304
+
`taxonomy_terms_cloud` with the only parameter `context` (most of the time the
305
+
current page or context `.`) and checks the taxonomy parameters of your
306
+
project's config to loop threw all listed taxonomies in the parameter
307
+
`taxonomyCloud` resp. all defined taxonomies of your page, if `taxonomyCloud`
308
+
isn't set.
199
309
200
310
## Multi language support for taxonomies
201
311
202
-
The taxonomy terms associated content gets only counted and linked WITHIN the language! The control parameters for the taxonomy support can also get assigned language specific.
312
+
For [multilingual sites][], taxonomy terms get counted and linked _within_ the
313
+
language site only. Taxonomy config parameters can be adjusted per language.
0 commit comments