GitHub Actions: Tag Page Generator for Jekyll Blogs

About a year or so ago, GitHub announced that GitHub Actions was generally available. GitHub Actions allows anyone to “automate their workflow” - in other words, run code on committed code - on GitHub’s own servers, and share those actions.

Being me, I wanted in on some of the action (pun definitely intended).

The Problem

This blog is hosted via GitHub pages. As such, it is a static blog generated with Jekyll.

Jekyll allows me to easier “tag” pages. For instance, this post has the tags github, jekyll, nodejs, and programming.

On other pages, I can easily query what tags exist, and what posts fall under those tags. For instance, this has allowed me to make the Tags page which lists every tag and every post underneath that tag.

What Jekyll doesn’t allow me to do - at least not straight out of the box - is to create a separate page for each tag that has excerpts for each post.

There is a Jekyll plugin to create page-per-tags, but it is not one of Github’s default Jekyll plugins.

If you are curious about what are Github’s default Jekyll plugins, check out the plugins section on the GitHub pages documentation and Dependency versions on the GitHub Pages site.

My Solution

As hinted by the introduction, I created a GitHub action that will read some data generated by a Jekyll blog and then create a markdown template for each piece of data.

I named my solution Tag Page Generator for Jekyll Blogs.

I wrote my solution in NodeJS.

It “requires” two packages from the GitHub Actions Toolkit - @actions/core and @actions/exec.

Also, it “requires” fs from the core NodeJS packages and node-fetch.

I (unit) tested my code with Jest, the delightful JavaScript Testing Framework.

GitHub Actions requires (or prefers) that the dependencies be installed in the repository along with everything else. This feels antithetical to what I’m used to, so I wanted to ensure I only committed exactly what I need. NodeJS, or rather npm, seemed to install a lot of superfluous stuff into the node_modules directory.

So I kept uploading stuff a little at a time until I could get my action to run without failing. On the eighth run, it was successful:

How to Use

1. Install the prerequisite files into your Jekyll blog.
2. Add the sample workflow to your Jekyll blog directory.

Options

Sample workflow

name: Generate the set of tag pages.
on:
  workflow_dispatch:

jobs:
  generate-tag-pages:
    name: Generate the set of tag pages.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: hendrixjoseph/jekyll-tag-page-generator-action@master
        with:
          source: "https://www.joehxblog.com/data/tags.json"
          destination: "./tags/"

Prerequisite Files

tags.json template

---
---

{% assign tags = site.tags | sort %}
{"tags":[{% for tag in tags %}
{"name":"{{ tag[0] }}","slug":"{{ tag[0] | slugify }}","postcount":{{ tag[1] | size }}}{% unless forloop.last %},{% endunless %}{% endfor %}]}

./layouts/tag_posts.html

---
layout: default
---

<span class="posts">
{% for post in site.tags[page.tag] %}<article class="post">
<h2 class="post-header">
<a href="{{ site.url }}{{ post.url }}">{{ post.title }}</a>
</h2>
<hr />
<div>
<span class="date">{{ post.date | date: "%B %e, %Y" }}</span>
<nav class="tags">{% assign tags = post.tags | sort %}{% for tag in tags %}<a href="/tags/{{ tag | slugify }}/">{{ tag }}</a>{% unless forloop.last %}|{% endunless %}{% endfor %}</nav>
</div>
<hr />
<div class="sample entry">
{{ post.excerpt }}
</div>     
</article>
{% endfor %}
</span>

Availablity

The source for Tag Page Generator for Jekyll Blogs is available on its GitHub page.

Tag Page Generator for Jekyll Blogs is also on the GitHub Marketplace.

To see some example pages, go to the Individual Tag Pages section of my sitemap. If you just want to quickly view one example, check out the money tag.