Migrating to 11ty

So, the first thing to mention about this post is: It's been years in the making! As I mentioned in my previous blog post, I've hated running my site on GitHub Pages and Jekyll for years now! So when I first heard that the wonderful Zach Leatherman had built an awesome new blogging framework that was built on Node.js back in December 2017, I thought, you know I need to migrate over to that ASAP! Then you find ASAP becomes weeks, weeks become months, and before you know it, the whole world goes through a global pandemic, and you get diagnosed with grade 3 brain cancer… Or maybe that's just me! It's just over 7-years since 11ty's first release, and I've finally got around to updating this blog! Finally moving away from GitHub Pages and Ruby, and embracing the future. I've decided to go all in with Node.js, Nunjucks, and Cloudflare. And as a bonus, this includes all the lovely web performance goodies that Cloudflare and Cloudflare Pages provide.

The Catalyst

So what was the catalyst, you may ask? Well, it all starts with a man in a red hat and who has a deep, booming voice. He is very well-known in the web community as he runs 2 fantastic conferences, State of the Browser (SotB), and also London Web Standards, among other things! Of course, I'm talking about the amazing Dave Letorey! Let me tell you a short story about how I first met Dave. I was in Amsterdam to speak at Performance Now 2023. Now, I'd love to give the somewhat predictable story of how he walked up to me after my talk and asked me to speak at State of the browser 2024, but as I've since learned, Dave likes to party! So I was sitting in front of Dave on the first day of Performance Now when he introduced himself. He said he was eagerly awaiting my talk tomorrow, and he's looking for speakers for SotB 2024, and would I be interested? I immediately said yes, thanked him, and started to watch the rest of the speakers from day one, while getting increasingly nervous all day, as the quality of the speakers at Performance Now are always incredible!

I was scheduled to be the first talk on the second day. After the quality of the speakers on day 1, I knew I was going to have a tough time keeping folks interested and engaged with my talk, especially after they've only just woken up and had their breakfast!

The next morning came and as I nervously scanned the audience, but I couldn't see Dave in the audience anywhere. I just assumed he was just a late riser, and he had decided to miss the morning talks. But as I mentioned, Dave likes to party, and it turns out, Dave had got very drunk the night before and ended up god knows where at 4am in Amsterdam! He admitted this to me later in the day once he'd arrived. He was very apologetic for missing my talk, as it had been one he'd been excited to hear! Thankfully (for Dave), the talks are recorded, so he'd get to watch it at a later date!

Fast-forward a couple of months, I was just about to start a new job, and just my luck, my health took another turn for the worse, so I reluctantly had to pull out of speaking at State of the Browser 2024. It turns out Dave is an incredibly kind and giving person, as he contacted me closer to the conference date and asked if I'd like to attend the conference as his guest. I agreed immediately, as it'd been several years since my last commute into London (thanks to COVID-19 and cancer!). So that's what I did, and boy I'm glad I took him up on the offer!

State of the Browser 2024

SotB always has some incredible speakers, you only need to look at their previous speaker list to see that! I enjoyed all the outstanding talks that day, but the one that resonated with me the most was Richard Rutter's talk on "Fluid typography (and its role in design systems)". Now, I've been a big fan of typography for many years, but I've never been particularly good at design. Even so, I like to think I can recognise good design when I see it. His talk goes over various typography topics like:

It was when Richard started to discuss the tool that his company Clearleft had built called utopia.fyi, it really got me thinking and genuinely excited.

If you get the chance I'd recommend you watch Richards talk, But In short, Utopia.fyi is a conceptual approach to fluid responsive design that encourages designers and developers to create systems where elements scale proportionally and fluidly across different screen sizes, without relying on arbitrary breakpoints (media queries).

This methodology promotes minimalistic and elegant design, enhances collaboration between design and development teams, and ensures visual harmony and consistency. To support this approach, Utopia offers free tools such as type, space, and grid calculators.

It was after he demoed the tools in action that I realised it was time to throw away my old website design and be brave and attempt to create something a lot more modern and simplistic. And with the help of utopia.fyi, I may actually be able to "design" it myself!

Throwing everything away

Once I'd decided that I wanted to throw away the old design, it actually made moving forwards a lot easier. My problem with simply migrating an existing design to any new framework is that I'd most likely migrate my "bad habits" and "technical debt" along with it. It was admitting this technical debt existed that gave me the freedom and the perfect opportunity to start from scratch and focus on building something I'd be happy to maintain into the future.

This was something I never had with Jekyll. I used to dread writing and trying to publish a new blog post after not doing it for a while. There was always the feeling that GitHub may have changed "something", and I was just about to run full-force into dependency hell just to get it published once written! It's safe to say that without Richard's inspirational talk, I'd still have "Migrate nooshu.com to 11ty" very much welded to my to-do list!

Learning 11ty

11ty 2.x.x

I swear I must be one of the unluckiest people I know when it comes to timings. 11ty version 2.0.x was released in February 2023, and the beta of version 3.0.0 had been in both alpha and beta release phases since June 2024. And of course, I picked the exact week 3.0.0 final was released to start my migration over to 11ty! At the start of the week, I began building from eleventy-base-blog v8, only to realise the scale of the differences between v2 and v3 were considerable for a beginner in 11ty like me. So I ended up scrapping my v2.0.0 version in favour of starting again using the latest eleventy-base-blog v9.

11ty 3.0.0

Having never used 11ty before, I wanted to stick as close to current "best practice" in the 11ty ecosystem as I could, so figured using the "eleventy-base-blog" would be the best place to start since it's maintained by 11ty creator Zach Leatherman. You can't really get much closer to the original source than that! Luckily, most of my v2 work like the CSS and partials could be easily migrated across to v3 without any issues. It was mainly the core of 11ty that had changed. Especially, it's adoption of ECMAScript Modules (ESM) for its configuration.

Minimal Viable Website

One of the problems with starting to migrate a live website from one technology to another is: at what point do you decide that the new site is "ready" to be published? It sounds simple, but it really isn't. It's far too easy to get greedy with functionality.

I found myself looking at other people's websites and saying: "Ooh! That's cool! I need to make sure I build that functionality before I put the site live!". And that's the slippery slope to a site that will never be published because it's never perfect. So I came up with a list for a Minimum Viable Website (MVW), off the back of a conversation with Sia Karamalegos, who'd I'd had the absolute pleasure of meeting at Performance Now too.

My MVW list looked like this:

As you can see, the list is already getting quite long! But just to make it a little more interesting, I decided to challenge myself to:

Now, many readers may be wondering why I've added some of these requirements into the build, isn't it just making life harder for myself? In all honesty, it's primarily for my interest and curiosity. The web is constantly evolving and moving forwards, and there's no better place to learn something new than your own personal website! Take CSS Variables for example, I've known about them for quite a while as I'd used to use their predecessor in Sass which had a similar variable implementation, but I'd never used native, web platform "vanilla" CSS Variables. And after using them I'm so glad I did, as it's going to make maintenance in the future much simpler!

Migration challenges

Here I'll go over a few of the pain points I found during the migration:

Cleaning up my content — Part 1

I've written quite a few blog posts since 2009, when I started blogging, and in that time I've migrated the content across multiple CMS's and platforms. I actually wrote all about it in a previous blog post. It probably took me around 1.5 weeks to complete the content migration task, doing the odd hour or so in the evening. What made matters worse is that during the migration from WordPress to Jekyll and GitHub pages, literally all the HTML character encoding across all blog posts broke! Thankfully, it wasn't noticeable at all to readers, but it's annoyed the hell out of me for years as it made my text editor light up like a Christmas tree. It also made spotting actual spelling errors much more difficult. This task in itself was very much a search and replace job, so it took a while!

Cleaning up my content — Part 2

Over the lifetime of my Jekyll build, I'd implemented some unusual non-standard ways to output elements like images. Basically, a simple abstraction layer include, that I added to make my life easier (in theory). As It turns out, it really doesn't when migrating to another blogging platform!

All of my images in every blog post looked like this:

{ % include image.html src="year/month/image-name.gif" alt="Alt Text here" caption="An example Caption here" % }

But in 11ty it all had to be changed. For 11ty, I've decided to use the more standard Markdown way of adding images. So the above code needed to be transformed into this:

![Alt Text here.](./year/month/image-name.gif)

The new markup is certainly a lot cleaner and easier to remember, but the only downside I've found is there's no support for image captions (<figure> & <figcaption>). FYI: This is still an issue I've yet to solve, so if anyone has added captions to their 11ty images output using Markdown, please do let me know!

Thankfully, there's a whole range of new tools on the web currently that can ease the pain of a migration process like this. It's a buzzword that is being crowbarred into pretty much every product and company presentation in 2024: "AI"!

I've used both the free and paid for versions of ChatGPT and Google Gemini, and both of these basic models are perfect for this type of repetitive, mundane work.

My methodology, was to get the basic prompt setup at first, e.g. "I want you to convert the njk image template into the md template", then see how well it did on its own. If there were issues, prompt it again to address the issues. Then keep repeating this process. And finally, once the output was what I needed it to be, I'd give it a prompt like: "That output format is perfect, do the same for each input I give you from now on".

From then on, simply paste in the old format and let AI generate the new format for you! Even that small workflow change literally saved me hours of manual copy / pasting into the new image template format.

I did wonder if I could prompt it to do this for a whole Markdown file from a post, but the prompt became so long and unwieldy, that I eventually gave up on that idea. But I'll take what I can from AI, every minute saved with the content migration task means more time to spend on more interesting tasks.

Observations

Here are a few observations I've made during my migration to 11ty:

Flexibility

11ty is unbelievably flexible in terms of how you set it up and the templating languages it can accept. I have to admit, in some ways it's almost too flexible for a beginner. A lot of the time I found myself asking: "Okay, I can do it that way… but is that the "correct" way to do it?". To give you a prime example of where I struggled, when I looked at the template languages documentation on this page, as a beginner I was overwhelmed by the number of options available to me.

I ended up using YAML frontmatter, Markdown for content, and Nunjucks for templating. A fairly standard setup coming from "Jekyll land". But I'm sure there are hundreds if not thousands of ways to achieve the same thing with all the templates 11ty supports. And as a beginner, it's challenging to know what the advantages and disadvantages are when choosing a particular templating language path. It's almost like a single paragraph is required on complex pages like this saying: "If you are a 11ty beginner, we'd recommend using a, b, and c because of reasons x, y, and z". Then, once a beginner is on a "safe" path to success, they can build up their confidence and start to evaluate other options and iterate accordingly.

Just so you know, this is in no way a dig at 11ty, I'm just feeding this back to (hopefully) help others who also find too many options a little overwhelming at first!

Unforgiving

I've found 11ty an unforgiving beast when it comes to error handling. If there's something wrong in the code, it will let you know about it! Even down to missing images that are referenced in blog posts! I believe that this is actually a good thing, and I want to applaud Zach for building it in this way. If I make such an obvious error like omitting an image file referenced in a blog post, I would like to be informed about it so I can fix it!

Although, at times, I did feel like Samuel L. Jackson's character in the original Jurassic Park (1993) when he repeatedly enters the wrong password into Nedry's computer! But all in all, it's a good to catch these really obvious mistakes early.

If there's one feature I'd like, it's to have a little "offline prompt" that is visible in the browser once the 11ty server goes offline (e.g. errors). This is just to make it blatantly obvious that something has gone wrong in the terminal. But it really is a minor issue.

Community

I have to commend Zach for successfully building such a strong and diverse community around 11ty! It really is a "poster child" of how an open-source project should be managed and, more importantly, how it should be funded!

There are so many resources available for beginners, like:

Honestly, I could go on, but I think you get my point!

Future Plans

So, what plans do I have for this blog in the future? I still have a list of functionality that I'd like to roll out at some point in the future, including:

  • Adding a plain text version of the RSS feed.
  • Make the source code to this blog available on GitHub (thanks for the inspiration, Sia Karamalegos).
  • Re-examining the use of pagination for the blog post homepage.
  • Built in search functionality (inspired by Tim Kadlec and WPOStats).
  • Add additional themes just because I can! (inspired by 11tytheme.sjoy.lol).
  • And finally, I have a list of around 5 or 6 smaller blog posts I want to write.

So, yes! Plenty still to be getting on with!

Thanks

Well, another blog post that turned out to be a lot longer than I first planned! Congratulations, you made it to the end! I hope you found it useful, as always, any feedback, please do let me know!

Finally, a heartfelt thank you to everyone who patiently answered my many 'n00b' questions during this migration process, including:

Post changelog:

  • 22/12/24: Initial post published.

Webmentions

No mentions yet.