Adding post series to this blog

Introduction

While writing my soon to be published article about the automated deployment workflow I setup for this blog, I realised the article was too long and so I cut it in 3 pieces. When doing so, I thought it would be good to have the ability to link blog posts together as part of the same series / collection so that it would be easier to navigate between linked articles. Something better than tags, which are useful, but not for the same purpose (many articles from other series or “standalone” could be tagged the same while not part of the same series).

I already had a “related articles” section at the end of each articles, but it shows 5 articles that may or may not be from the same series (which is normal, this section show articles with similar tags). I ended up adding this capacity to this site while polishing the first 2 posts of the next series about the deployment workflow…

Let’s go through the results and then I’ll detail how I set this up with Hugo.

Results

First, let’s see what I’m talking about. Series are now visible in multiple area of this website.

Post page

For any post/article marked as part of a series, a new area at the bottom will be shown indicating that this post is part of a series (and its name) and will show the links of all the posts of that series. A picture might be easier to understand:

Series page

There is also a new series page showing all the different series available on this blog. Clicking on their title will send you to a page listing all articles of that series, like the laptop series page. The series page is linked in the footer.

For posterity, it looks like this as of today:

Current and future series

I’ve updated old posts to add 3 already existing series:

• Frame.work laptop setup: All posts related to my frame.work laptop setup (8 so far)
• Homelab 2020: All posts related to my previous homelab setup (from 2020 to 2023, 11 posts). A new series is coming for the 2023/2024 version!
• HomeAutomation 2020: Same as above but for the Home Automation related posts (8 posts). I don’t have any in my new flat yet

I have 3 additional series in mind for this year:

• Unnecessary Complex Deployment Workflow: the post that was too long and started all this…
• Homelab 2023/2024: I’ve teased about it already enough, at least the 1st post is already started…
• Backup strategy: I’ve put many automated backups based on borg (and proxmox) for both my servers and my laptop and I intend to detail all that this year…

Hugo Setup

Let’s talk about the how of all of this.

Taxonomy setup

First, a taxonomy needs to be created. For that, I added in my config.toml:

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

The series = 'series' part being the new part in the configuration.

To tag multiple posts part of the same series, all I need is to add the series parameter and its value in the frontmatter area, for example:

+++
title = "New laptop part 0: Discovering the FrameWork laptop"
date = 2023-01-16
tags = ["framework", "laptop"]
categories = ["laptop"]
series = "Frame.work laptop setup"
+++

All posts with the same series defined in their frontmatter will be part of that series. So easy!

Templates

To add the area for other links from the same series, I simply edited an existing partial I had already customized (article-extra.html). Until now, this partial was used to for the indienews section (read more) and the contact area at the bottom. I simply added a test to check if the “series” taxonomy is declared in the frontmatter. If that’s the case, the list is retrieved and displayed. The relevant part of the partial is:

{{- if .Params.series -}}
    <div class="toc">
      <h4>From the « {{ .Params.series }} »: collection:</h4>
        <ul>
            {{ range $num,$post := (index .Site.Taxonomies.series (strings.ToLower .Params.series )) }}
                <li><a href="{{ $post.Permalink }}">{{ $post.Title }}</a></li>
            {{ end }}
        </ul>
    </div>
{{ end }}

The only important part to understand being:

{{ range $num,$post := (index .Site.Taxonomies.series (strings.ToLower .Params.series )) }}

This part retrieve all the posts from the series taxonomy (.Site.Taxonomies.Series) where the name of the series equals the one given in the frontmatter declaration (.Params.series).

Then simply displaying a list of links.

Bonus: Add an introduction before list of posts

On the series page, you can see an introduction before the list itself. This is not done by editing the template (as I’m using the default listing one here), but by simply creating a content/series/_index.md file with the following content:

---
title: "Blog Post Series"
---

Blog posts series are usually multiple [blog posts](/posts/) about the same subject and usually dependent of each others.

You can follow series (the list of series, not posts within series) via [RSS](/series/index.xml).

To follow posts of a specific series, add `index.xml` at the end of the series page url. For example, fo the [laptop series](/series/frame.work-lap    top-setup/) ([rss](/series/frame.work-laptop-setup/index.xml)): `/series/frame.work-laptop-setup/` → `/series/frame.work-laptop-setup/index.xml`.

Conclusion

Well, all that pushed back the 1st article about the deployment workflow (for a day or 2 tops) as I wanted this to be ready before publishing it. But I’ve been thinking on an off each time I wrote posts in multiple part… So now it is there and I don’t have to think about it anymore.

The most important part for me was the links at the bottom of the page of an article, to ensure one could easily navigate to just read a post series in a row without too many clicks. The rest, like the page of feeds, are just easy bonus thanks to Hugo awesomeness!