Sam Hooke

Hugo tag and category pages

Taxonomies are ways of grouping content within Hugo. By default, Hugo defines two taxonomies: “tags” and “categories”. You can then, for example, write a post and define tags = ["test"] in the front matter. Hugo will then generate a taxonomy list page at https://mywebsite.com/tags/ and you can view all posts with the "test" tag at https://mywebsite.com/tags/test.

As far as Hugo is concerned, there is no difference between “tags” and “categories”. Each post can have as many tags and/or categories as you would like!

Conceptually though, I consider “categories” to be the broad topic, and “tags” to be more specific aspects. For example, for this post I might set:

categories = ["software", "web-dev"]
tags = ["Hugo", "taxonomies"]

Plural vs singular taxonomies §

So far we have been using “tags” plural. For this website, I instead wanted the taxonomy list page to be https://mywebsite.com/tag singular. It turns out this is rather easy!

To use singular rather than plural, override the default values for the tags and categories taxonomies:

config.toml
[taxonomies]
# Use singular rather than plural for default taxonomies
tag = "tag"
category = "category"

As shown above, the [taxonomies] section of the config file defines a list of key/value pairs, where the key is the singular term, and the value is the plural term. Hugo uses the plural term of the taxonomy for the list page URL, so by making this singlar we get the URL we desire.

You can then go to https://mywebsite.com/tag/ to view the list of tags.

Templates §

In order to customise things further, you can modify the templates used:

  • layouts/_default/terms.html is the template for https://mywebsite.com/tag/, which lists all the terms for that tag.
  • layouts/_default/taxonomy.html is the template for https://mywebsite.com/tag/term/, which lists all the pages for that term.

The Hugo documentation has a good starting point for writing your own taxonomy templates.

Disabling taxonomies §

To disable the default taxonomies entirely, simply set their values to empty strings.

config.toml
[taxonomies]
# Disable the default taxonomies
tag = ""
category = ""