# Taxonomy support
> Organize content with tags, categories, and custom taxonomies.
---
LLMS index: [llms.txt](/llms.txt)
---
Oink supports Hugo [taxonomies][] in its docs and blog sections. You can see the
default layout and can test the behavior of the generated links on this page.
## Terminology {#terminology}
To understand the usage of taxonomies you should understand the following
terminology:
- **Taxonomy**: a categorization that can be used to classify content - e.g.:
Tags, Categories, Projects, People
- **Term**: a key within the taxonomy - e.g. within projects: Project A, Project
B
- **Value**: a piece of content assigned to a term - e.g. a page of your site,
that belongs to a specific project
A [movie-website sample][] taxonomy is provided by the Hugo docs.
[movie-website sample]:
https://gohugo.io/content-management/taxonomies/#example-taxonomy-movie-website
## Parameters {#parameters}
There are various parameters to control the functionality of taxonomies in the
project [configuration file][]. Taxonomies are [enabled by default][] for `tags`
and `categories` in Hugo. To **disable** taxonomies, add the following to your
project config:
**Configuration file:**
```
```
**hugo.toml**
```toml
disableKinds = ["taxonomy"]
```
**hugo.yaml**
```yaml
disableKinds: [taxonomy]
```
**hugo.json**
```json
{
"disableKinds": [ "taxonomy" ]
}
```
With the default settings, Hugo generates taxonomy pages for `tags` and
`categories`. 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.
With the following example you define a additional taxonomy `projects` beside
the default taxonomies `tags` and `categories`:
**Configuration file:**
```
```
**hugo.toml**
```toml
[taxonomies]
tag = "tags"
category = "categories"
project = "projects"
```
**hugo.yaml**
```yaml
taxonomies:
tag: tags
category: categories
project: projects
```
**hugo.json**
```json
{
"taxonomies": {
"tag": "tags",
"category": "categories",
"project": "projects"
}
}
```
You can use the following parameters in your project's config to control the
output of the assigned taxonomy terms for each article resp. page of your docs
and blog sections, plus a taxonomy cloud in Oink's right sidebar:
**Configuration file:**
```
```
**hugo.toml**
```toml
[params.taxonomy]
taxonomyCloud = ["projects", "tags"] # set taxonomyCloud = [] to hide taxonomy clouds
taxonomyCloudTitle = ["Our Projects", "Tag Cloud"] # if used, must have same length as taxonomyCloud
taxonomyPageHeader = ["tags", "categories"] # set taxonomyPageHeader = [] to hide taxonomies on the page headers
```
**hugo.yaml**
```yaml
params:
taxonomy:
taxonomyCloud:
- projects # remove all entries
- tags # to hide taxonomy clouds
taxonomyCloudTitle: # if used, must have the same
- Our Projects # number of entries as taxonomyCloud
- Tag Cloud
taxonomyPageHeader:
- tags # remove all entries
- categories # to hide taxonomy clouds
```
**hugo.json**
```json
{
"params": {
"taxonomy": {
"taxonomyCloud": [
"projects",
"tags"
],
"taxonomyCloudTitle": [
"Our Projects",
"Tag Cloud"
],
"taxonomyPageHeader": [
"tags",
"categories"
]
}
}
}
```
The settings above would only show a taxonomy cloud for `projects` and `tags`
(with the headings "Our Projects" and "Tag Cloud") in Oink's right sidebar and
the assigned terms for the taxonomies `tags` and `categories` for each page.
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 = []`.
By default, the plural label of a taxonomy is used as its cloud title. You can
override 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!).
If you don't set the parameters `taxonomyCloud` resp. `taxonomyPageHeader` the
taxonomy clouds resp. assigned terms for all defined taxonomies will be
generated.
## Partials {#partials}
The partials used by default for displaying taxonomies are defined so that you
can easily use them in your own layouts.
### `taxonomy_terms_article` {#taxonomy_terms_article}
The partial `taxonomy_terms_article` shows all assigned terms of a given
taxonomy (partial parameter `taxo`) of an article respectively page (partial
parameter `context`, most of the time the current page or context `.`).
Example usage in `layouts/docs/list.html` for the header of each page in the
docs section:
```go-html-template
{{ $context := . }}
{{ range $taxo, $taxo_map := .Site.Taxonomies }}
{{ partial "taxonomy_terms_article.html" (dict "context" $context "taxo" $taxo ) }}
{{ end }}
```
This will give you for each in the current page (resp. context) defined taxonomy
a list with all assigned terms:
```html
```
### `taxonomy_terms_article_wrapper` {#taxonomy_terms_article_wrapper}
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 through all listed
taxonomies in the parameter `taxonomyPageHeader` resp. all defined taxonomies of
your page, if `taxonomyPageHeader` isn't set.
### `taxonomy_terms_cloud` {#taxonomy_terms_cloud}
The partial `taxonomy_terms_cloud` shows all used terms of a 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.
Example usage in partial `taxonomy_terms_clouds` for showing all defined
taxonomies and its terms:
```go-html-template
{{ $context := . }}
{{ range $taxo, $taxo_map := .Site.Taxonomies }}
{{ partial "taxonomy_terms_cloud.html" (dict "context" $context "taxo" $taxo "title" ( humanize $taxo ) ) }}
{{ end }}
```
This will give you the following HTML markup for the taxonomy `categories`:
```html
```
### `taxonomy_terms_clouds` {#taxonomy_terms_clouds}
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 config to loop through all listed taxonomies in the parameter
`taxonomyCloud` resp. all defined taxonomies of your page, if `taxonomyCloud`
isn't set.
## Multilingual taxonomy support {#multi-language-support-for-taxonomies}
For [multilingual sites][], taxonomy terms get counted and linked _within_ the
language site only. Taxonomy config parameters can be adjusted per language.
[configuration file]:
https://gohugo.io/configuration/introduction/#configuration-file
[enabled by default]:
https://gohugo.io/content-management/taxonomies/#default-destinations
[multilingual sites]:
https://gohugo.io/configuration/params/#multilingual-projects
[taxonomies]: https://gohugo.io/content-management/taxonomies/