Trying some templating

As part of “The story so far” I learned some HTML, CSS and a little typography, and I’m happy with how the posts are looking. But before writing too many more, I decided to look at whether a templating system would be useful.

Writing pages directly as HTML does work, but there’s lots of repetitive stuff — and as I change the site structure, I’ll need to go and change every page (if I want navigation across the top, sidebars or other things).

I can imagine in a site where every page has different layout and features, sticking with that might be a good choice, but for a blog where I want to make lots of similar pages then some more separation of structure from content would be useful.

There’s lots of options, but an obvious choice to try first is Jekyll: it’s fairly well-liked, and I believe it’s already running in GitHub Pages as standard.

Some background

Like lots of web topics, I’ve heard bits and pieces of tech in this area but really haven’t been closely following things. Looking into current options can feel a bit like joining a conversation that’s been going on for 20 years. For static site generators (of which Jekyll is one), I very much appreciated this SSGs through the ages tour, filling me in on lots of missing context. The series starts with a Carl Sagan quote: “You have to know the past to understand the present.”

Jekyll started in 2008 and still seems popular today, partly because it’s been built right into the easy-to-use GitHub Pages from the start. There are a wide range of more modern choices but I don’t see an obvious winner … I’ll have a go with this and move to something else if any limitations annoy me.

I like the idea of it because:

• If you give it normal HTML, CSS and JS that just leaves it untouched — that’s actually what GitHub pages is doing now — so I can still do as much tweaking and bespoke stuff as I like.
• You can write Markdown pages that are a lot simpler than HTML, they look just like plain text — these should be easier for me to write, fewer pointy brackets to get in the way.
• You can use “front matter” and Liquid templating to separate out “common” things, like the nav bar and layout of every post, meaning you just write it once.

Getting started

GitHub have a step by step guide for setting up Jekyll for GitHub Pages. You need to install Ruby, which I did using Homebrew and then set the $PATH to it.

The instructions say to install Bundler … but apparently that’s part of Ruby’s standard library now, nothing to do here.

The next step, gem install jekyll hits an error: in compiling some C++, I get fatal error: 'iostream' file not found. Looks like others have found C++ compiler issues after moving to MacOS Sequoia, that’s what I’m on … tried removing and reinstalling the XCode command line tools and now gem install jekyll works.

This got all sorted very quickly, but it wasn’t obvious. It‘s the kind of minor issue that comes up all the time in tech: the exact weird error I hit is because of the exact combo of versions of my OS and the things I’m installing. It’s not in the instructions because it wasn’t happening a few months ago, and if someone comes to try this in a few more months it might be a different minor hiccup. I used to get very stuck on things like this but I feel I’ve had a lot of practice now finding ways to navigate them. Don’t let things like this put you off trying stuff.

The instructions assume I’m starting from scratch: is there a way to turn my existing site into a Jekyll-powered one? I found the perfect blog post to answer this question from Danny Garside, and thanked them on Mastodon.

Following that guide, I ran jekyll new --skip-bundle --force ., changed some config file values, and was ready to run the site locally: bundle exec jekyll serve makes the site available in a browser.

It looks nice — a little too nice! The initial setup gives me a theme, and creates an automatic summary of all posts, with various navigation things. I decided to delete all these and go right back to basics.

Rewriting my HTML pages in Markdown

A good test of how much easier I’ll find this than writing bare HTML.

I’ve used Markdown for other things in the past, I’m a big fan of it.

• It was helpful to read over the basics again.
• The Markdown All In One VS Code extension makes editing it a really nice experience.
• And once I was happy with how to translate between HTML and Markdown, the HTML to Markdown extension lets me select and convert anything very easily.

Writing the content for a new post in VS Code is fine, I’m doing it now! And separating out the standard _layout works well, you can see exactly what it’s doing.

Separating this out and rewriting the first page in Markdown looked fine locally, and then I pushed it into GitHub left the live site looking exactly the same. Perfect!

Getting images to work nicely

I’ve been using figure and figcaption to caption my images, and can’t see a way to get Markdown to do that. I could use the HTML syntax every time I add an image, but is there an easier way?

There’s lots of additional features available as Ruby Gems — I found jekyll-figure does exactly what I want and it was easy to add to my site’s config. Turn the paragraph setting off and it works perfectly.

Then, I made a lucky spot: the {% highlight %} tag in jekyll for code highlighting uses a figure too, I accidentally started applying my image and caption styling to that.

• figure:has(img) lets me target just figures that have images.
• This is a fairly new CSS feature, and the “Can I use” site has stats on how well it’s supported.
• I’m not too practised on how to interpret those stats, but I got helpful advice on Bluesky and then found a lovely interactive guide to evaluating browser support.

This worked great on my local machine, so I checked it into GitHub … and it failed horribly:

After this anyone going to neil-vass-2.com just gets a 404, it’d be great to not change anything in the live site on failed builds! Clicking to see the details on that failed step brings up a dauntingly big message.

It says it can’t install a gem, and doesn’t recognize the figure tag I’m using. Ohh … there’s a set of plugins in GitHub pages, and this new one isn’t on there. But this error points to a solution: that link on line 12 has a guide to using GitHub Actions to give me more control over things like this. Followed the steps and it’s working fine!

One more thing … relative links

The files I write for each page have names like 2025-06-08-trying-some-templating.markdown, and I’ve set Jekyll up to change that into a URL like neil-vass-2.com/trying-some-templating. When I link from one page to another, I could just write the eventual URL, but I wanted to check if we can do something smarter.

I found a helpful guide to URLs and links in Jekyll from Michael Rose — I’m sure I’ll come back to this, there’s a lot you can choose to do. For my current question, it recommended a jekyll-relative-links plugin that works nicely. I can use ../relative.markdown links when I write pages and they get converted to the right thing when the site builds.

Some very nice behaviour I’ve found: any heading you make in Markdown gets rendered with a helpful id you can use as an anchor to link directly to that section. And when you start typing ../, VS Code completion offers you all the filenames at that location, then goes on to offer all the anchor links too. That’s such a good editing experience!

Next time

I’m very happy with Jekyll so far, it’s done just what I was looking for: let me separate out the common parts from my posts, and made page authoring much simpler.

Next, I’ll use this separation to start adding more of the features I should have around the post content. Header, footer, and various other bits to make this more of a blog and not just individual pages. Should be fun.