The Jekyll Rabbit Hole

It Was Innocent At First

I really only wanted to just build the stylesheets and layouts from scratch. I wasn’t thinking about building plugins or anything. Then I started thinking, “Oh, I need to have an archives for my articles because the number of articles will grow and I want to have this tree hierarchy index page for all the articles sorted and grouped by year/month/day.”

And then I built this thing called “Shots”, which are supposed to be like “Shorts” for articles. And another thought came about, “Oh, this list is also going to grow, and I’m building a static site, so I’m not going to have infinite scroll and I need to have pagination for my shots for my own (and my precious readers’) sanity.”

So I did what most DRY supporters would do, which is to go look for existing solution from Jekyll Plugins documentation page and Awesome Jekyll Plugins. Indeed, what I needed were already solved by other brilliant developers, and I was quick to install the jekyll-archives and jekyll-paginate-v2 plugins for my site.

It’s Not You, It’s Me

But then things didn’t go as smoothly as I imagined when I started configuring the plugins for my site. I don’t think there’s anything wrong with the plugins, these are plugins that have been used by many other Jekyll users (in the range of 600K to 800K downloads as of the time of writing). I think it’s because of my peculiar use cases that these plugins don’t fit anymore. Let’s see why.

For archiving, I wanted to have a sort of tree hierarchy for year, month and day, so it feels like navigating the site directory. The official plugin doesn’t really do that, it just generates the index pages for the posts that belong in each year, month and day. I might be able to write some scripts that build a tree hierarchy based on the generated index pages, but I thought that would be odd because clearly the plugin, while perfectly functional, doesn’t fit my use case.

Then for pagination, I wanted to have the first page of the paginated collection as a root-level page, like /shots.html, so that I can put it in the navigation menu. The official plugin doesn’t really allow for that, it will always generate all index pages under the same directory. I tried to hack around it to make the first page go to /shots.html, but I failed to make it work. Again, it’s a perfectly functional plugin, it just doesn’t do what I wanted.

But I’m An Engineer, Right?

So I did what most engineers would do when they face a problem with no existing solution, they fix it for themselves, and so did I.

Luckily for me, I’ve been coding in Ruby for the past 6+ years, so the only learning curve for building a Jekyll plugin is figuring out its interfaces. The good thing is that there are already many existing Jekyll plugins on Github, and the Jekyll project is also open-source. By reading through the source code, I figured out the structure of building a Jekyll generator plugin.

And so, I built the coffeebrew_jekyll_archives and coffeebrew_jekyll_paginate plugins, and use them on my site. Voila! Now I have a tree hierarchy for archives and pagination that allows me to put the first page in the root.

It’s Not For Everyone

Even though I published the gems, and wrote pretty extensive READMEs for them (as if there would be other contributors reading them), my true intention is only to use them for my site. I’m fully aware that these are built specific to my own use case, and may not be useful for many others. Similar to what I encountered at first, someone may try to install these plugins, and think that they don’t actually fit their use case. That is perfectly fine.

I’m also aware that my plugins have missing features. For example, the archives plugin doesn’t archive based on tags or categories, and it only works for site posts and not other collections. I do plan to add these features slowly when I face the need myself. Or, if in the unlikely event that the plugins almost do what you want them to, but just miss out on these features, you are very much welcome to submit a feature request or better still, a pull request.

One More Thing

So the archives and pagination plugins aren’t the only plugins I have built, for the purpose of rendering the README for the plugins on a Jekyll-powered site, I have also built a theme for the README documentation sites. And since I need to use the theme on 2 sites, I figured that I might as well package it into a theme plugin.

For this one, I’m pretty certain no one else will have the same use case as I do, but for some miraculous reason that you do want to use it and again, missing certain features, you are very much welcome to submit a feature request or a pull request.

I’m Done, For Now

And that’s the rabbit hole I’ve jumped through in the past week while building this site. It certainly took many cups of coffee to come out of it, but it was a totally fun and enjoyable process. I think I’m done building this site for now, and I will go on to build the apps I’ve wanted to build.