Learning Jekyll

I’ve been trying to teach myself how to use Jekyll to see if it can help me set up static websites that aren’t dependent on a CMS with a database. My needs have changed and for the state of my webcomic site today, WillowCMS is very over-engineered. For example, I no longer allow comments on the website; the website updates sporadically and most of the features that WillowCMS supports have never been used. Some of those features are now obsolete because they’re API calls to external services that no longer exist. Even though Willow works pretty fast, it still has considerable overhead and maintenance needs that are no longer worth it for me. So I’m looking at alternatives.
For the past year, my thinking about what to do with the website is that the images should be larger and everything else should be smaller, in terms of both screen real estate and file size. The new placeholder page has a minimalist HTML template with a very simple style sheet, no javascript, no external embeds and no logo images. As it happens, the placeholder does not have a comic image either, but that won’t be the case for a full webcomic site, obviously. The total code for the HTML+CSS is about 4 KB in decimal KBs. Because it is not served through a scripting language and a database, it gets rendered almost instantaneously. I want that for the website as a whole: rendering so fast that on a good internet connection, it is almost like an eBook, and on a satellite connection in some rural backwater in the United States, it’s still pretty tolerable and doesn’t use up limited data. So, since authoring 1300 static pages by hand is a bit of a drag, I’m looking at static site generators, and Jekyll seems to fit the bill.

Problem is, the learning process is not going well. Part of it is my own impatience: I did about half of the basic tutorial on the Jekyll website before I started thinking about what I needed specifically to run a webcomic site through it, which is not a default use case and wasn’t really addressed in the rest of the tutorial when I skimmed through it. Webcomics have needs such as scheduled incremental updates (less of a problem for me today) and the ability to process a large number of very similar image files into separate web pages quickly. The tutorial is light on info on how to work with images and the use cases that Jekyll showcases aren’t very like a webcomics site. So I googled and found some plugins and themes that would be able to handle the webcomics use case.

The first I looked at was the Jekyll webcomics plugin from Nompute. The webpage for that showed the code and an explanation of what it does, and had a statement at the end that inspired confidence:

There’s probably a more efficient way to do this, but the code works well enough for a couple hundred comic pages.

I thought “a couple hundred comic pages will do quite nicely”. I had already decided that my test project would be only ten pages long, but it would be nice to know that an archive the size of Rogues of Clwyd-Rhan would be within the plugin’s capabilities. I’m learning that the Jekyll community puts a high value on speed of output generation. Personally, that is nowhere near as important to me as the speed at which the static pages can be served to readers, but I might change my mind if I had to generate a site over and over again.

Unfortunately, the first build of my test site using this plugin failed with the error jekyll 3.8.5 | Error: no implicit conversion of nil into String and I entirely lack the skill to follow up on that*, beyond a Google search that left me none the wiser.
Another problem was that while there is program logic included, it does not come with the layout files or instructions on how to use the variables. Probably not a problem if you already know Jekyll well, but for me as a beginner, I need a little more to work with.
After some deliberation, I abandoned this plugin and went to the second option I’d found, the Webcomic Jekyll Theme from Peahatlanding.

Eh. I don’t even remember what went wrong when I tried to run it locally, but it didn’t seem to do much. Because the instruction for this theme relied heavily on GitHub, I tried to run it on my own GitHub account with GitHub pages, but files did not appear to be generated even when the instructions said they would. As there were apparently technical difficulties behind the scene (site updates not working at all, according to emails from GitHub with the recommendation to try again later), I decided that I was not going to spend any more time on that one either. GitHub isn’t any easier to use than the local shell if you’ve never used GitHub for anything before.

OK, so a common theme is that when I abandoned the tutorial for whatever shiny trinket I’d found on the web, I was clearly trying to run before I could walk. I simply lack the expertise to tackle problems as they occur. But I do think the complexity and the sheer number of dependencies aren’t helping. Jekyll relies on Liquid templating, which relies on Ruby which runs in the command line or inside GitHub. It consists of a large number of small program files and plugins, any of which could be a failure point. Compared to simply hardcoding dozens of very similar pages in an editor, there’s a trade-off: less tedious, repetitive and error-prone work, a greater risk of the whole thing falling apart intractably.

I have one more plugin I want to try for my test project. It was given to me personally by Yncke of Yncke.be who uses it for webcomics in multiple languages, and they kindly supplied layout templates as well. But I’ve decided to sit on it and go back to the tutorial for a bit, followed by an attempt at making a simple site. So my new project is expanding the ROCR.net placeholder (link may vanish once the site is back up fully) into a small emergency website with about pages and whatever I can salvage from the cast pages, before tackling a small webcomic project with actual webcomic pages. Then I will start looking at Yncke’s plugin again.

And indeed, it turns out that there are places where Jekyll simply breaks on my system. It took me about an hour of trial and error getting template code to show on character pages to determine that, on my MacBook Pro, Front Matter Defaults do nothing at all. I have to hand-code the front matter on every individual character page. Or, as I type this, I realize it may be a mistake on my part after all. But I’m trying to limit the time spent to a few hours a day and this time is already up, so I will revisit that tomorrow or whenever I have some time**.

*update: I have learned how to backtrace in Jekyll and that may help.
**update 2: It was an error on my part that I have now fixed. I was literally in the middle of a sentence that said “but having to hand-code that stuff is no big deal as I would need to put empty front matter on any page that has front matter defaults anyway”, when I realized that I had removed the front matter entirely after specifying the defaults. So I restored the defaults in _config.yml, edited the front matter in the affected pages and tried again, and lo, it worked. This is exactly why I write walls of text like this: so I can both track what I’ve learned and what I’m still struggling with, and go over my thought process once again so I can come up with solutions.