Bryan Lee
Musings about product, growth, and software engineering.

Migrating Hugo to Eleventy - Initial Thoughts

· Jamstack

I've just spent one afternoon and a couple of hours after dinner migrating this blog from Hugo to Eleventy and also refreshing the design a little. The paint has not even dried yet but I am really amazed and delighted about how enjoyable and easy the migration was.

Why Eleventy?

Hugo has been perfectly fine for my blog, but as my projects at work are going towards more JAMStack, I thought I'd update myself about the latest developments in this area. Eleventy caught my attention primarily due to it being written in JavaScript which is something I am extremely at home with.

The other very interesting point about Eleventy is that it aims to be as agnostic as possible. It does not take a stance between React or Vue, and you can freely choose to write your layouts in Liquid, Nunjucks, Pug, or just plain HTML. You can also have different layouts written in different languages.

Smooth setup and migration process

The whole process from installing Eleventy to publishing it live on Netlify took me 5-6 hours, not bad considering that I also rewrote the HTML and CSS again from scratch. Disclaimer alert - my blog is a simple website.

Migrating my blog post markdown files over was fairly easy. I had to tweak the front matter a little to make them compatible with Eleventy. I was using tags in Hugo for grouping my posts, but tags are used by Eleventy Collections in a slightly different manner and didn't really transfer over. I had to rename a couple of other attributes too, but nothing too difficult for a few full-text search and replaces.

No Webpack

One thing you'll quickly notice is the glaring absence of Webpack. I needed to handle image assets and also to use SCSS. No biggie too, there is already a SASS plugin for Eleventy. Eleventy does not support SVG files by default but there is also a community plugin to cover this. No Webpack was involved at all and I found this really refreshing without having to fiddle with Webpack config files and getting my hands all greasy.

Intuitive templating system and awesome documentation

I rewrote the HTML and CSS from scratch with some tweaks to the design and found the Eleventy documentation to be really well-written. I loved how you can just chain layouts together to create different variations. The directory structure is also really simple. All layouts go into the _includes folder, and you specify in your front matter which layout you want.

# Specifying layouts
layout: layout.liquid # Loads layout from _includes/layout.liquid

Eleventy also has this concept of Data Cascading to merge data from various sources. You can use this to specify that you want all your blog posts to load a different template from your sitewide default, and you can also even load a post-specific template. I like this declarative approach much more than directory-based inheritance approach which Hugo used.

// posts/posts.json - Data here affects all your posts content
{
  "layout": "blog-post.liquid" // All your posts will use the layout from _includes/blog-post.liquid
}
# posts/special-post.md
layout: special-occasion-layout.liquid # Only this post will use a different layout from the rest of your posts

Unopinionated and flexible

Eleventy comes with support for a range of templating languages out of the box (Liquid, Nunjucks, HAML etc). As I wrote in the beginning of this post, you can also use different languages for different layouts. I loved not being forced into a templating language that I'm not familiar with or one that I'm not a fan of. I decided to go with Liquid (yay Shopify) which itself is also really pleasant to work with.

I also see how Eleventy is just plain Javascript and not built on top of React, Vue or any other framework a huge plus. Given how fast things move in the frontend world, you could wake up tomorrow and X framework is no longer cool. Plain old JavaScript will always be here, and I can always write my own Eleventy plugins without having to keep up with a framework I may not be familiar with.

What about the bad?

I've been singing praises for Eleventy this entire post. Does this mean Eleventy is the best static site generator there? I definitely don't think so. I've still not spent a lot of time with Eleventy yet. My experience so far has been these couple of hours migrating from Hugo although it has been a very pleasant one indeed. My blog is also a very simple website which also means I am not pushing Eleventy to its limits yet. As I play around more, the parts where Eleventy do not do well will start to be more visible and I hope to do another post on this then.

Adding a headless CMS

Once you have Eleventy set up, the next thing you might want to consider is adding a headless content management system (CMS) so that creating and managing blog posts is easier. One option that I went with is Sanity.io. In this next post, I share how I integrated Sanity.io with Eleventy.