Migrating to Hugo

Back in August I rebuilt the site using Jekyll and Minimal Mistakes for the theme. This worked great for a few months, but even a small site was taking too long to generate (10-15 seconds!)

While 15 seconds per build isn’t much, it was just enough friction to make updating not fun. That’s when I remembered that Julia Evan’s had posted her experience switching to Hugo. A zero second build time was very attractive!

Unlike her, it took me longer than four hours to migrate my site to Hugo! I had used a bunch of helpers provided by Minimal Mistakes that I had to either replace or rebuild. Plus, I had also written a couple of my own custom Jekyll plugins which were converted to Hugo shortcodes.

Migrating to Hugo

Like Julia I started with:

  1. run hugo import jekyll
  2. import a random theme

Getting to this point took no time and a hugo run to build the entire site took 150ms! Milliseconds! Awesome!

Then I hit the hard part. :(

Rebuilding the Existing Theme

I had spent a lot of time before settling on Minimal Mistakes as my Jekyll theme. It’s a great design with lots of functionality (some of which I even used.)

Rather than trying to port the underlying Jekyll templates, layouts, etc. I did what Julia did and copied the generated HTML and assets into the layouts directory of the new site and started digging into the Hugo documentation: while extensive, it’s not exactly user-friendly.

It took me three days of intermittent hacking to ensure all the content was present, with the right URLs, and with all the old Minimal Mistakes helpers removed and my custom plugins written as Hugo. (Lots of NeoVim editing to replace the old markup.)

Once the HTML looked right, the last step was to update my workflow scripts.

Gotchas

Parsing dates.

Hugo has the .Format function to parse dates into human readable strings. What I didn’t grasp is that the reference format is very specific. If you don’t format the string using the exact times mentioned in the documentation your rendered dates are all messed up!

Success!

With everything in place I can now publish to the site with way less overhead and friction. Effectively, I go from saving the post to publishing to the Internet in under a second!

The only way it could be better is if I didn’t have to do the pesky writing as well!

Update

Still using Hugo, but switched out Minimal Mistakes for a theme I found online and then customized to suit my preferences!