Moving this blog from Jekyll to 11ty

A couple of gotchas but mostly very straightforward

Rebuilding my personal site is always going to be very low on my list of priorities: at the time of doing it this site was running on a version of Jekyll 3 major versions behind latest. I also had no problem with Jekyll, it just worked! Which in my world is ideal.

However, getting a new computer meant installing all the relevant ruby dependencies and I hit a wall that I couldn't get past. Rather than go down the rabbit hole of OS/Ruby/Gem compatibility, I decided to finally make the move away from Jekll and Ruby.

I wanted to choose something that was easy to convert to and used JavaScript. 11ty seems to be the popular choice right now so I ended up with that. All in all it probably took around 6 hours of work, spread out over multiple days - not too bad - though I cut some corners along the way to make my life easier.

Getting started

I asked on twitter originally to get some advice on where to begin and was pointed to a few resources including this article from Paul Robert LLoyd.

In the end I decided to rebuild from a boilerplate, specifically Phil Hawksworth's EleventyOne. It gave me:

The 11ty docs are great and I leaned on them a lot during the process. If you're doing a similar process to me I would recommend reading and understanding the sections on Collections and The Data Cascade. I had to refer to these often but once I got my head around them it really made the work smoother.

Gotchas along the way

What about Sass?

Phil's boilerplate doesn't include Sass. Whilst there are quite a lot of other Starter Projects that do have them I decided that I didn't need this dependency any more and converted mine back to CSS.

My styles were written in indented syntax (that's how old this site is) so I converted that back to SCSS using SassMeister and then converted the Sass variables to custom properties. The mixins and extends were just removed and replaced with good old-fashioned duplication.

All my content was suddenly wrapped in a <pre> tag

This was a strange one, that has come up in a couple of issues before. The problem was that certain includes were being rendered as preserved markup rather than being interpreted as DOM elements:

This turned out to be a markdown issue. When you indent a certain amount in markdown it preserves the whitespace and wraps it in a pre element. In my template I was using the following data but you can see the outcome below:

layout: layouts/base.njk
pageClass: posts
templateEngineOverride: njk, md

To fix this, I removed the md directive from the templateEngineOverride. I'm not sure if this is the truly correct solution but after this it rendered just fine.

Listing recent posts in the sidebar of a post page

11ty has good support for pagination but there were two things I couldn't initially figure out:

I needed these because I list various categories of post in the sidebar on each page. Whenever I tried to add the pagination data on a post page I would get the following error:

Problem writing Eleventy templates: (more in DEBUG output)
> Dependency Cycle Found: ___TAG___all -> ./src/site/posts/a-post.md -> ___TAG___post -> ./src/site/posts/a-post.md

`Error` was thrown:
    Error: Dependency Cycle Found: ___TAG___all -> ./src/site/posts/a-post.md -> ___TAG___post -> ./src/site/posts/a-post.md

It made sense that this would cause some cyclical dependency issues but i wasn't sure how to fix it. Eventually, after referring to the docs, I realised I could control all of this in the eleventy configuration file. I used the following to make the sidebar:

config.addCollection("sidebarRecent", (collection) => {
  return collection.getFilteredByTag("post").slice(-5);
});

config.addCollection("sidebarFewer", (collection) => {
  return collection.getFilteredByTag("fewer_words").slice(-5);
});

config.addCollection("sidebarNonTech", (collection) => {
  return collection.getFilteredByTag("non_tech").slice(-5);
});

I could then iterate over these different collections in the sidebar and add headings.

That was it

The rest was just me fiddling around with templates and trying to remember how to do front end development again. All the code for this site is available on Github if you're interested. It's by no means good code but it does the job and I no longer need to install Ruby on this computer!