Create a blog post series with navigation in Jekyll

Blogging about individual self-contained ideas is great. However, some ideas require a more structured approach. Combining simple concepts into one big whole is a wonderful journey for both the writer and the reader, so I wanted to add a series feature to my Jekyll blog. As you may have guessed already, Jekyll's high degree of customization makes this a breeze.

Goal

I want to achieve the following goals:

1. Each article should list the other articles in the same series.
2. To simplify content discovery, the home page should display all series in a category.
3. Moving articles into different series should be easy since they may evolve over time.

Step 1: Add series metadata to posts

Given Jekyll's high customizability, there are several ways to handle a series. I can leverage Jekyll variables in the config to keep a series list, use collections, or define a Liquid list somewhere in a global template and iterate over it.

The cleanest way is to list the series and the posts contained in that series. For example, for all the posts in the Jekyll series, I've added the following two variables in the post front matter:

is_series: true
series_title: "Jekyll"

The first variable, is_series, is a simple boolean which says whether this post is part of a series. Booleans work great with Liquid filters and allow me to filter only those posts which are part of a series. This comes in handy later on when I'm trying to list all the series in one go.

The second variable, series_title, is the title of this series. In this case, it is Jekyll. It's important that posts in the same series contain the same title. I'll use this title to match posts to a series. If it contains extra spaces or special characters, it won't match the series.

You can view the source code here.

Step 2: Add links to posts

With the series defined, I now need to show other articles in the series. If I see a post in the Jekyll series, there should be a list of other articles in the same series. A series won't make sense without this essential navigation.

My blog uses the posts layout to display posts. To show other posts in the same series as the currently viewed post, I use the code below:

<!-- Series links -->
{% if page.is_series == true %}
<h3 class="text-success p-3 pb-0">{{ page.series_title | upcase }} series</h3>
{% assign posts = site.posts | where: "is_series", true | where: "series_title", page.series_title | sort: 'date' %}
 
{% for post in posts %}
        {% if post.title == page.title %}
 <p class="nav-link bullet-pointer mb-0">{{ post.title }}</p>
        {% else %}
 <a class="nav-link bullet-hash" href="https://opensource.com/%7B%7B%20post.url%20%7D%7D">{{ post.title }}</a>
        {% endif %}
{% endfor %}

{% endif %}{% endraw %}

The logic above is as follows:

1. Check if the is_series boolean of the current page is true, meaning the post is part of a series.
2. Fetch posts where is_series is true and series_title is the current series_title. Sort these in ascending date order.
3. Display links to other posts in the series or show a non-clickable span if the list item is the current post.

I've stripped some HTML out for clarity, but you can view the complete source code here.

Step 3: Add links to each series to the home page

I now have the post pages showing links to other posts in the same series. Next, I want to add a navigation option to all series under a category on my home page.

For example, the Technology section should show all series in the Technology series on the home page. The same for Life Stuff, Video Games, and META categories. This makes it easier for users to find and read a complete series.

<!-- Series posts -->
{% assign series = "" | split: "," %}
{% assign series_post = "" | split: "," %}
{% assign posts = site.posts | where:"Category", cat.title | where: "is_series",true | sort: 'date' %}

{% for post in posts %}
{% unless series contains post.series_title %}
{% assign series = series | push: post.series_title %}
{% assign series_post = series_post | push: post %}
{% endunless %}
{% endfor %}

{% if series.size > 0 %}
<div class="row m-1 row-cols-1 row-cols-md-4 g-3 align-items-center">
 <div class="col">
 <span class="h3 text-success">Article series →</span>
 </div>
    {% for post in series_post %}
        {% include card-link.html url=post.url title=post.series_title %}
    {% endfor %}
</div>
{% endif %}
{% endfor %}{% endraw %}

To identify all series for a particular category, I use the code above, which accomplishes the following:

1. Initializes two variables: one for series names and another for the first post of each series.
2. Fetches all posts that have is_series set to true and belong to the current category.
3. Adds the series_title to the series names array and the first post to the series post array.
4. Displays the name of the series, which links to the first post in that series.

You can find the full source code here.

Why I love using Jekyll for blogging

Jekyll's high degree of customization is why I enjoy working with it so much. It's also why my blog's underlying Jekyll engine has survived redesigns and refactors. Jekyll makes it easy to add dynamic logic to your otherwise static website. And while my website remains static, the logic that renders it doesn't have to be.

You can make many improvements to what I've shown you today.

One improvement I'm thinking of is handling series post ordering. For example, the posts in a series are currently shown in ascending order of their publish date. I've published several posts belonging to a series at different times, so I can add a series_order key and use it to order articles by topic rather than by publish date. This is one of the many ways you can build your own series feature.

Happy coding :)

This article originally appeared on the author's blog and has been republished with permission.