Use Custom Taxonomies in Hugo

Since I started using Hugo, I have appreciated its flexibility and the ease with which it can be extended. I’ve written about Custom Taxonomies, using these to show featured and related content … but now I want to explore it further.

Your Hugo theme will likely support the two most popular taxonomies out of the box - tags and categories … and being able to create custom taxonomies allow you to go further - create a product shop, event calendars, recipe library, photo galleries, book reviews, authors, portfolios and more.

One subtle point - you might already be using custom taxonomies in your Front Matter without realising it - for featured posts, series of content or portfolios.

This article will guide you to:

1. Understand benefits of Custom Taxonomies
2. Change your front matter
3. Create list pages for custom taxonomy to your Hugo config
4. Resolve any errors

If you have a theme which doesn’t have a list layout … then choose a better theme :)

Benefits of Custom Taxonomies

There are benefits from using custom taxonomies which you can’t get if you just use Front Matter, these include:

• Creating pages showing content in each Taxonomy - showing content that are in a Taxonomy from a specific Series such as a magazine issue or series name
• List Pages for showing Taxonomies attributes - creating a list of all the Series names, such as magazine issues or meal types
• Use custom code to filter, sort and show taxonomies - creating a widget of the top 3 related content in a Series

If you want to do any of these, then you need to add your Custom Taxonomy to your Config

Front Matter Changes for Custom Taxonomy

This step is the easiest - and is over to you … taxonomies and relationships are in your hands

If you’re creating a Taxonomy called Series, then maybe the top of your markdown files will look like this:

1
2
3
4
5
6
7
8
9

---
title: "My content title"
date: 2020-08-01
tags: 
- hugo
author: Your Name
draft: false
series: My Custom Taxonomy
---

Add Custom Taxonomy in Config

So you can have custom taxonomy page or create widgets or other code … then open your config file and add this in:

1
2
3
4

[taxonomies]
    category = "categories"
    series = "series"
    tag = "tags"

Having done this you can browse to your custom taxonomy using the pluralised name in the quote marks.

When adding custom taxonomies, you need to include the default taxonomies too, if you want to keep them.

Test and Go …

So now you’ve enabled your custom taxonomy …

1. Create some markdown content and add your custom taxonomy
2. Commit your changes to Git
3. Run Hugo server -D and browse to http://Localhost to check every thing is work fine
4. Browse to http://localhost/your custom taxonomy/ and check you get a list of content in your taxonomy

If you find a problem

• check what is saved in the config
• have you added the custom taxonomy to any content?

Meet the author

Damien Saunders
An experienced management consultant and business leader interested in digital transformation, product centred design and scaled agile. If I'm not writing about living with UCTD (an autoimmune disease), I'm probably listening to music, reading a book or learning more about wine.
Find our more about me.