Taxonomies

We can create arbitrary site-wide groups of content with joint taxonomy terms.

What are taxonomies and their terms?

Formally, taxonomy terms are a third type of content structure after single pages and list pages.

Normal list pages present an overview of the contents that are stored in their folder. Taxonomy terms don’t have a folder – instead, they are added to the frontmatter of single pages. Every page with a certain taxonomy term then belongs to a new group and all its pages are shown on the special list page of this term. There is in principle no limit to the number of taxonomy terms a page may belong to. (→ Hugo documentation for taxonomies)

As regards content, taxonomy terms should describe an actual relation between their pages – a relation in the broad sense, a similarity for example may also be considered as one. There are a few well-established taxonomies that represent specific types of content relations with their terms:

Categories
form a general classification of the contents. They aim to be mutually exclusive to separate the contents into distinguishable parts. → Every page should get only one of the category terms and their groups should be of a roughly similar size. In practice, these goals are usually not met completely.
Tags
are labels describing one aspect or property of the content. → Every page may have a few tag terms.
As the content grows we should check for tag terms that still contain only one page. This often happens in the beginning but is a good reason to remove a term in the long run.
And when we end up adding a term to the majority of our pages, we should consider using more fine-grained terms instead.
Series
are pages that are tied directly together – postings about the exact same topic for example or a long article split into a few parts. series is defined as a taxonomy for this theme but it doesn’t show on pages. It’s only meant to increase the score for the related content section.

We can define new taxonomies to establish other relation types (→ Hugo documentation for taxonomies). Author names for example are usually not understood as taxonomy terms but to be an author of some pages can be recognized as a special kind of relation.

Related content

Many templates for single pages generate a small section of related content (See also …). The pages in this list are selected by calculating a score from joint taxonomy terms to estimate the strength of their relations. We can control this calculation in the section related of the site configuration:

threshold: 30
includeNewer: true
toLower: false

indices:
  - name: categories
    weight: 30
  - name: tags
    weight: 40
  - name: series
    weight: 30

The key indices holds the list of taxonomies that are used to calculate the relation score. They all have a weight to quantify their importance.

The parameter threshold contains the minimal relation score which is included in the list of related pages.

If includeNewer is set to false the related list excludes content with a date after the current one.

How to add taxonomy terms?

The introduction to content generation describes how to add taxonomy terms and how to generate content files for taxonomy terms.

How to generate an overview for taxonomies?

Every taxonomy has a list view showing small cards for all its terms and the number of pages they contain.

We can create an explicit content file for this list view with a command like:

hugo new tags/_index.md

As for the taxonomy terms, there is usually not much content to add. We can provide the description as a subtitle and a featured image which may be used as a fallback for taxonomy terms without their own.

Every list of taxonomy terms also includes automatically a conveniently small list of all taxonomies and their terms at the bottom or the side.

See Also