Creating a Series taxonomy in Hugo

Hugo’s taxonomies feature is very flexible and covers a lot of use cases for organising static content.

One thing I use it for on several static sites is to create a Series taxonomy that allows an easy grouping of posts into a sequence. Readers can see other posts in the series on each post, like a table of contents, they can see next and previous links within the series, and they can view a dedicated list page for the series as well.

The first thing is to configure a Series taxonomy in Hugo’s config file, e.g. in TOML:

[taxonomies]
	series = "series"

This will replace the default tag and category taxonomies if you don’t explicitly include them in the config as well:

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

Note the singular = "plural" structure of the TOML config there.

You can now assign individual posts to a Series in their front-matter like this:

series:
 - My Lovely Series Title

That post is now part of the “My Lovely Series Title” series. In theory you could assign a post to multiple different series, but that doesn’t fit the model here.

The next thing you might want to do is render a table of contents for the series on each page that appears in it, i.e. showing other pages in the same taxonomy term.

You can achieve the list with some templating like this:

{{ if isset .Params "series" }}
{{ $seriesTitle := index .Params.series 0 }}
{{ $currentLink := .Permalink }}
<h2><small>Series:</small>&nbsp;{{ $seriesTitle | title }}</h2>
<ol>
  {{ range (index .Site.Taxonomies.series ($seriesTitle | urlize)).Pages.ByWeight.Reverse }}
  <li>
    {{ if eq $currentLink .Permalink }}
    	{{ .Title }} <small>(this page)</small>
    {{ else }}
    <a href="{{ .Permalink }}">
      {{ .Title }}
    </a>
    {{ end }}
  </li>
  {{ end }}
</ol>
{{ end }}

That will render a list of all the posts in this series. You might include that in the layouts/_default/single.html template file to display it all individual pages that have a series assigned.

The easiest way to control the ordering within the series is with a taxonomy weight in each page’s front-matter:

series_weight: 1

This is especially useful if you don’t write the posts in chronological order, or you don’t want to tweak post dates to keep them in the order that makes sense for the series.

I use this approach on East Asia Student for series of posts, e.g. Lu Xun’s Diary of a Madman and The Diary of Yangzhou.

You might also want to add links to the previous and the next page within the taxonomy term as well.