Migrating from Middleman to Eleventy

Before sharing some of the details and process I used to migrate this site from Middleman to Eleventy, I think it’s helpful to provide some context behind my choice.

First and foremost, there’s not a damn thing wrong with Middleman. 🤷🏻‍♀️ Honestly, working on Middleman had only gotten easier for me since I had been developing on Windows back when I started the site in 2015 and had since moved to a Macbook. While I was running on an out-of-date version of Middleman¹, I didn’t foresee problems updating the Middleman gem or the site.

Three things led me to redo things in Eleventy:

1. I had elected to use Eleventy in the advanced web development course I teach at MICA² and running my site on the same generator would give me more experience using and configuring Eleventy.
2. Eleventy is so awesomely flexible. While I was initially sold on the minimal configuration, with Eleventy that only means you don’t have to customize things, but you certainly can. The ability to use multiple templating languages, to use JavaScript for all sorts of logic, to work with data in a variety of formats–Eleventy is simple to set up, adaptable and powerful. It’s a great choice for what I’m doing now with the site and really anything I want to do in the future.
3. Community – I find the creator (@ZachLeat) to be a stand-up dude (see, for example, his enthusiasm when I tweeted about teaching with Eleventy) and the community around Eleventy to be friendly and encouraging.

Setting up Eleventy #

Because I thought I might want to archive the previous version of the site (this migration also included a redesign), I opted to create a new GitHub repo for the blog. I’m not precious about my git history, so this was an easy choice for me to make.

After creating a new repo, I copied the Eleventy base blog template for the basic structure.

At this point, I copied over the content from my existing blog and started troubleshooting what was broken or wonky.

Content tweaks #

• I updated all my filenames to use a .md extension instead of .html.markdown and removed the date from the filename; this was an expectation of Middleman’s blogging, but always struck me as ugly and wonky.
• I updated my front matter to remove the time because it wasn’t in a format that Eleventy was parsing (I got the time for free when creating new blog posts via the Middleman CLI, but didn’t use it in my UI) and to add square brackets around my tags.
• My actual Markdown content required two updates. First, I had to change the way code blocks were identified (Middleman uses tildas and I needed to change that to the ` symbol. Also, Middleman let me get away with not having a space in my markdown headings (e.g., ##A second-level heading), but Eleventy had issues with this, so I added the space everywhere.

Once I identified issues, these updates were easy to make in bulk via the command line (for filenames) or the search and replace UI in VS Code.

Additionally, I had missed that I was using some Markdown plugins and sorted out how to add and configure those in Eleventy.

Finally, Middleman allowed me to write draft posts and identify them by adding published: false to the post’s front matter. This doesn’t work the same way in Eleventy, so I moved this content instead to a _drafts folder and added that to my .eleventyignore file. At this point, it was also important to clean my build folder and restart my server to make sure draft content wasn’t showing up on the site.

Build changes #

One of the things Eleventy gives me more control over is my asset and build pipeline. While Sass compiled ✨automagically✨ with Middleman, this is not the case with Eleventy. Configuring this is not my favorite part of web development, so I mostly wanted a build process that was as straightforward as possible. So, uh, no webpack. I opted to use Parcel (since I was already succesfully using it on a work project), but expect there’s lots of cleanup and/or optimization I can do here. I may also try out Snowpack at some point in the future since I’ve heard good things.

Finally, actually deploying/publishing my Middleman blog had been a fairly wonky, almost embarrassing process³ where I built the site locally and then used the command line to push the static output to my web server. Just wholesale copying over the whole directory. I did it infrequently enough that it always felt fraught and required several “notes to self.” I knew there were other options, like hosting on S3 and having a pipeline based on merging into my git repo, but hadn’t gotten beyond the research stage about how to do that (well, and tweeting about it and soliciting help from my great pals).

As my redesign was nearly complete, I explored deploying the site using Vercel and damn if it isn’t simple and great. Other than adding my domain name (and sorting out my mail servers), I’ve had to do zero customization there – it just works. After I merge changes into my main branch on GitHub, the site is live in about a minute. Legit, I used to spend more time than that verifying my old command line process. 🙀

Wrapping up #

There was a lot more involved in redesigning the site, tweaking Eleventy and using Nunjucks templating, but at this point in my process I had successfully migrated my content from Middleman to Eleventy. 🙌🏻 For the redesign, it’s worth mentioning that I relied heavily onNunjucks documentation, 11ty Recipes and Andy Bell’s Learn Eleventy From Scratch course.