Custom Jekyll Generators with GitHub Pages

A Learning Moment

When attempting to publish this Jekyll blog using GitHub Pages for the first time, it became immediately obvious that something wasn’t right – pages that were supposed to be generated by plugins weren’t present. For context, I had created custom plugins to generate index pages for each category and tag. These plugins were closely modeled after the CategoryPageGenerator sample that Jekyll’s generator documentation outlines. Locally, everything looked okay, even using the github-pages gem. Why, then, didn’t these generated pages show up when published?

As it turns out, GitHub Pages builds Jekyll artifacts using the --safe flag. One of the primary effects of this flag is that only a handful of curated plugins may be used. Had I known this at the time of theming my blog, I likely would have made some different design choices. But I like the idea of having category and tag indexes. It offers the readers an easy way to find content related to the exact topics that they may be interested in. Therefore, I made the decision that I would keep them.

The question became… how?

A Gordian Knot

After about two hours of scouring both GitHub’s and Jekyll’s documentation for answers, as well as a handful of blogs and issue threads, it seems that there were three options:

Use a custom or third-party GitHub Actions workflow to publish the blog
Create each page manually
Do away with the idea of category and tag index pages altogether

These options left me with somewhat of a Gordian knot scenario. For the reasons already mentioned above, doing away with the idea was out of the question. Creating pages manually, even with the help of a Python script that generates them, is tedious, and would likely still rely on the first option. Lastly, configuring a custom or third-party GitHub Actions workflow simply represented more effort than I was willing to give to this particular problem.

Cutting the Knot

In order to cut this proverbial Gordian knot, I had a fallback. I could simply remove the build artifacts of jekyll build from repository’s .gitignore. It’s certainly not the most eloquent solution…

It creates noise in the repository
It forces me to suppress my OCD tendencies

But it’s not all bad. There are a handful of beneficial side effects. Since GitHub Pages isn’t being leveraged to build the Jekyll artifacts…

I can replace the github-pages gem with jekyll in my Gemfile
I can use newer Jekyll versions, which means leveraging an up-to-date Sass compiler
Most importantly, I am not beholden to GitHub’s restrictive list of approved Jekyll plugins

Resolution

Just two more hidden (but quick) steps were necessary. By default, GitHub Pages only publishes from the root or docs directory. So, I had to ensure that the GitHub Pages settings pointed to the docs directory, and then change Jekyll’s build destination directory to docs by including the following line in the _config.yml file:

...

destination: "docs"

...

Lastly, GitHub Pages looks for a CNAME file in the directory it publishes from (in this case, docs). I created a CNAME file with a single line in the repository root with my custom domain:

crafttheory.blog

When building, Jekyll will copy this CNAME file to the docs directory along with the rest of the build artifacts.

Success! The blog maintains the structure that I prefer, and the sacrifice to make it so was minimal.

Custom Jekyll Generators with GitHub Pages

Published June 26, 2022 at 12:24 pm