On moving my blog to Hugo


After finally deciding to throw caution to the wind and move my webstuff back into a static format, this website finally landed on Hugo. I did an initial migration from WordPress to Jekyll, which looked really promising but took waaaaay too long to generate the 2,800+ posts for this site (taking almost 45 minutes?). Hugo runs as a native application, and runs MUCH faster. Generating the entire site currently takes less than 5 seconds, then uploading it to the server via rsync takes only a little longer.

Why I wanted to move:

  • I was really really tired of managing performance issues with WordPress.
  • Future-proofing. Static files will probably work forever, but a version of WordPress that relies on a version of MySQL and a version of PHP and updating versions of plugins and themes and a version of JQuery and a version of who knows what is just a ball of trouble waiting to happen. Static site generators will still have issues, but once the site is published it should just work. Leaving someone to inherit a slowly-crumbling tech stack just to keep content online felt like more risk than it’s worth.

As I migrated to Hugo, a bunch of issues came up.

  1. The theme I used seemed to want to generate an RSS file including every single post. So, it was over 6MB, and kind of blew up any RSS readers that grabbed the file before I realized what had happened and figured out how to override that strange behaviour. The RSS feed now includes 15 posts.
  2. Search! One of the big reasons for having a blog rather than just a notebook somewhere is that it’s searchable. But without WordPress providing search, what to do? Easy. DuckDuckGo has an embeddable site search, and is now included at the bottom of every page.
  3. URL permalinks - I had to do some minor tweaking to the permalink structure so posts generated by Hugo match the URLs that had been published by WordPress over the last decade and a half or so. Search results should now match up with where pages are expected.
  4. I keep my documents in the iCloud-managed Documents folder. Which is great, but when Hugo generated the thousands of text files that make up this site, the public directory apparently started to freak iCloud sync out. I had one build where index.html files got duplicated - were they collisions with iCloud sync? I’ve now told it to build the website into /tmp/public and will upload those files onto the webserver rather than keeping the output in the iCloud-synced Documents directory. Keeping the source and config files there should be enough for portability.
  5. rsync uploads - the site gets uploaded to the same directory that my website has lived for many years. So there’s a lot of stuff there that isn’t managed by Hugo (and wasn’t managed by WordPress previously). So, I need to be careful not to use the –delete flag and accidentally delete a bunch of older static files.
  6. Authoring new posts - having the web UI for WordPress was nice, being able to just edit something on the fly and be done with it. Now, I need to create a markdown file, make sure the frontmatter metadata is correct, edit the file, put it in the right folder, run hugo build, then rsync. It’s definitely not as smooth of an editing process - but that, I’m hoping, will be either a good thing (forcing me to slow down and be more intentional about how I write), or at least not so painful that I wind up looking to move to something else…
  7. Footnotes. I’d been using a WordPress plugin to convert ((double brackets)) to footnotes. Now they’re just regular text, which is silly. I need to figure out how to replicate that functionality.
  8. Media management - it was super easy to add images to a WordPress post. I need to get used to a different workflow, and the lack of mobile publishing ((which didn’t really work reliably for posting images anyway, so maybe that’s no big loss)).
  9. Embeds - the WordPress oembed feature is pretty handy. Now all youtube etc. content in existing posts is just a raw URL to the media, rather than an auto-embedded media player. There must be a way to reproduce that functionality, even if it’s just a script that pre-processes raw URLs and converts them to the embed version.
  10. Comments. I could enable Disqus. Not sure if I want to do that.

So. Now, source and config files are in my ~/Documents/Blog/hugo directory and editable on any computer I use (or via the iCloud web interface). Output is generated by Hugo running on my laptop, and saved into /tmp/public, and then uploaded via rsync to my Reclaim Hosting webspace at ~/public_html.

My plan is to get the configuration set up smoothly enough that I can just double-click an icon on my Mac and it’ll build the entire site and rsync it to the server without any intervention needed, in only a few seconds.

I think I have it mostly working as intended now. I’ll be working to tweak the layout of the site a bit, to replicate the Pages from the old WordPress site. Or not. It’s a fresh start. Ish.

hugo  blog 
comments powered by Disqus