How to create series in the LoveIt theme - Hugo

2024-01-12 936 words 5 minutes

Contents

LoveIt is an amazing theme for Hugo; it has a lot of features, it’s slick, good looking, and I find it quite good for reading.

That being said, it lacks something I needed: the ability to create series.

After reading documentation and testing, I finally came up with something to get the series feature in LoveIt theme.

Create the taxonomy

A series is, in essence, a tag we apply to several pieces of related content, stating that they should be read in order. Like a story, a course, or a tutorial to build a blog site. First this chapter, then this one, this one, and so on.

To create this feature, we are going to use the Hugo taxonomies.

We will modify the Hugo blog config file. Depending on what you chose when creating the blog, it will be called hugo.json, hugo.toml, or hugo.yaml (and depending of the version of Hugo you use, it will be config, instead of hugo).

We will add these lines to create the series taxonomy:

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

Warning: Probably you are already using the categories and tags, but once you add an extra taxonomy, you must include them in the file or they won’t work!

We have our new taxonomy created. Now it is time to make it available to the reader.

For that, I have chosen to create a new entry in the top menu, as tags and categories.

We will modify the Hugo blog config file mentioned earlier, and this time we add the following entry to the menu:

[[menu]]
...
  [[menu.main]]
    weight = 2
    identifier = "series"
    pre = ""
    post = ""
    name = "Series"
    url = "/series/"
    title = ""
...

Here, we are telling Hugo to show another menu entry, that will be mapped to the /series/ path, using the same logic as tags and categories have.

If you refresh your site now, you’ll see the new entry. If you click there, you will see a page - instead of a 404 - but probably it will be an empty one.

Create the code for listings for the new taxonomy

Your page is empty because Hugo is not aware about how it should present the series.

But if you go to <hugo_blog_root>/themes/LoveIt/layouts/taxonomy/terms.html you will find the logic to show the categories and tags.

We will leverage this and add this code to let Hugo know how to show the series taxonomy:

{{- /* Series Page */ -}}
{{- else if eq $taxonomies "series" -}}
    <div class="categories-card">
        {{- range $.Site.Taxonomies.series.ByCount -}}
            <a href="{{ .Page.RelPermalink }}">{{ .Page.Title }} <sup>{{ .Count }}</sup></a>
        {{- end -}}
    </div>

Basically, I have copied the code from the tags, and applied the div class of the categories, to have the same css applied to it.

You can play with the properties there, but with this simple code, you can check the series page, and see it … if you have applied any series value in the front matter of any post! No? That’s the next step.

Assign a post to a serie

Now that we have the code to see the series, it’s really easy to assign a post to one of them. You just add this line to the front matter (example in YAML):

1
2
3
4
5
6


---
title: "my first episode"
...
series: ["my first serie"]
...
---

Do that for a couple of posts, and check the results in the series page!

Create the partial code for the posts

Ok, we have now a page that shows our series, can navigate to the pages, read them and have a feeling of relationship between them. But we need to go back to the series page to see what is the following chapter.

Wouldn’t it be nice to see the series and the parts in the current post we are reading? And wouldn’t be convenient to be able to click to the next chapter, instead of going back to the main series page? Yes, it would be very nice, and to do that, we are going to leverage the code provided in this page: https://digitaldrummerj.me/hugo-post-series/

Following its directions, we will create a “partial”, that is a small piece of code to show html based on logic.

Create this file <hugo_blog_root>/themes/LoveIt/layouts/partial/series.html, and add this code:

  {{ if .Params.series }}
<div>
      <h4>This article is part of the series "{{ .Params.series }}".</h4>
    <ul class="list-group">
        {{ range $num,$post := (index .Site.Taxonomies.series (index .Params.series 0 | urlize)).Pages.ByDate }}
            {{ if eq $post.Permalink $.Page.Permalink }}
                <li class="list-group-item active">
                    Part {{ add $num 1 }}: This Article
                </li>
            {{ else }}
                <li class="list-group-item">
                    <a href="{{$post.Permalink}}">
                        Part {{ add $num 1 }}: {{ $post.Params.title}}
                    </a>
                </li>
            {{end}}
        {{end}}
    </ul>
</div>
{{end}}

This code will only execute if the page we are going to attach it to contains the parameter series.

Assign the partial code to the posts

Now, we go to the <hugo_blog_root>/themes/LoveIt/layouts/posts/single.html - the place that contains all the code to show a post - and add a single line, highlighted in the code below:

{{- /* Subtitle */ -}}
{{- with $params.subtitle -}}
    <h2 class="single-subtitle">{{ . }}</h2>
{{- end -}}
{{ partial "series.html" . }}
{{- /* Meta */ -}}
<div class="post-meta">
    <div class="post-meta-line">
        {{- $author := $params.author | default

I have chosen that place because I consider it a nice place to have that information, but you can play and adapt to your liking.

Now, when you visit a post that is part of a series, you will all the related posts and their order. Isn’t it nice?

Happy Hugo blogging!