---
title: Taxonomy Support
weight: 10
tags: [Tagging, Structuring Content, Labelling]
categories: [Taxonomies]
description: >
  Structure the content using taxonomies like tags, categories, labels.
cSpell:ignore: taxo
---

Docsy supports Hugo [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.

## 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

There are various parameter 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:

<!-- prettier-ignore-start -->
{{< tabpane >}}
{{< tab header="Configuration file:" disabled=true />}}
{{< tab header="hugo.toml" lang="toml" >}}
disableKinds = ["taxonomy"]
{{< /tab >}}
{{< tab header="hugo.yaml" lang="yaml" >}}
disableKinds: [taxonomy]
{{< /tab >}}
{{< tab header="hugo.json" lang="json" >}}
{
  "disableKinds": [ "taxonomy" ]
}
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->

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.

With the following example you define a additional taxonomy `projects` beside
the default taxonomies `tags` and `categories`:

<!-- prettier-ignore-start -->
{{< tabpane >}}
{{< tab header="Configuration file:" disabled=true />}}
{{< tab header="hugo.toml" lang="toml" >}}
[taxonomies]
tag = "tags"
category = "categories"
project = "projects"
{{< /tab >}}
{{< tab header="hugo.yaml" lang="yaml" >}}
taxonomies:
  tag: tags
  category: categories
  project: projects
{{< /tab >}}
{{< tab header="hugo.json" lang="json" >}}
{
  "taxonomies": {
    "tag": "tags",
    "category": "categories",
    "project": "projects"
  }
}
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->

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/or blog section in Docsy or a "tag cloud" in Docsy's right sidebar:

<!-- prettier-ignore-start -->
{{< tabpane >}}
{{< tab header="Configuration file:" disabled=true />}}
{{< tab header="hugo.toml" lang="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
{{< /tab >}}
{{< tab header="hugo.yaml" lang="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
{{< /tab >}}
{{< tab header="hugo.json" lang="json" >}}
{
  "params": {
    "taxonomy": {
      "taxonomyCloud": [
        "projects",
        "tags"
      ],
      "taxonomyCloudTitle": [
        "Our Projects",
        "Tag Cloud"
      ],
      "taxonomyPageHeader": [
        "tags",
        "categories"
      ]
    }
  }
}
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->

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.

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 = []`.

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!).

If you don't set the parameters `taxonomyCloud` resp. `taxonomyPageHeader` the
taxonomy clouds resp. assigned terms for all defined taxonomies will be
generated.

## Partials

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.

### taxonomy_terms_article

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 `.`).

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 gave you for each in the current page (resp. context) defined taxonomy
a list with all assigned terms:

```html
<div class="taxonomy taxonomy-terms-article taxo-categories">
  <h5 class="taxonomy-title">Categories:</h5>
  <ul class="taxonomy-terms">
    <li>
      <a
        class="taxonomy-term"
        href="//localhost:1313/categories/taxonomies/"
        data-taxonomy-term="taxonomies"
        ><span class="taxonomy-label">Taxonomies</span></a
      >
    </li>
  </ul>
</div>
<div class="taxonomy taxonomy-terms-article taxo-tags">
  <h5 class="taxonomy-title">Tags:</h5>
  <ul class="taxonomy-terms">
    <li>
      <a
        class="taxonomy-term"
        href="//localhost:1313/tags/tagging/"
        data-taxonomy-term="tagging"
        ><span class="taxonomy-label">Tagging</span></a
      >
    </li>
    <li>
      <a
        class="taxonomy-term"
        href="//localhost:1313/tags/structuring-content/"
        data-taxonomy-term="structuring-content"
        ><span class="taxonomy-label">Structuring Content</span></a
      >
    </li>
    <li>
      <a
        class="taxonomy-term"
        href="//localhost:1313/tags/labelling/"
        data-taxonomy-term="labelling"
        ><span class="taxonomy-label">Labelling</span></a
      >
    </li>
  </ul>
</div>
```

### 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 threw all listed
taxonomies in the parameter `taxonomyPageHeader` resp. all defined taxonomies of
your page, if `taxonomyPageHeader` isn't set.

### taxonomy_terms_cloud

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.

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
<div class="taxonomy taxonomy-terms-cloud taxo-categories">
  <h5 class="taxonomy-title">Cloud of Categories</h5>
  <ul class="taxonomy-terms">
    <li>
      <a
        class="taxonomy-term"
        href="//localhost:1313/categories/category-1/"
        data-taxonomy-term="category-1"
        ><span class="taxonomy-label">category 1</span
        ><span class="taxonomy-count">3</span></a
      >
    </li>
    <li>
      <a
        class="taxonomy-term"
        href="//localhost:1313/categories/category-2/"
        data-taxonomy-term="category-2"
        ><span class="taxonomy-label">category 2</span
        ><span class="taxonomy-count">1</span></a
      >
    </li>
    <li>
      <a
        class="taxonomy-term"
        href="//localhost:1313/categories/category-3/"
        data-taxonomy-term="category-3"
        ><span class="taxonomy-label">category 3</span
        ><span class="taxonomy-count">2</span></a
      >
    </li>
    <li>
      <a
        class="taxonomy-term"
        href="//localhost:1313/categories/category-4/"
        data-taxonomy-term="category-4"
        ><span class="taxonomy-label">category 4</span
        ><span class="taxonomy-count">6</span></a
      >
    </li>
  </ul>
</div>
```

### 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 threw all listed taxonomies in the parameter
`taxonomyCloud` resp. all defined taxonomies of your page, if `taxonomyCloud`
isn't set.

## 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/getting-started/configuration/#configuration-file
[enabled by default]:
  https://gohugo.io/content-management/taxonomies/#default-destinations
[multilingual sites]: https://gohugo.io/configuration/params/#multilingual-sites
[taxonomies]: https://gohugo.io/content-management/taxonomies/