Frustration of a Hugo Blog Migration

This is the first blog post I’ve made since migrating to this new domain and blog space. I didn’t intend for this to be my first post. Quite the contrary, I anticipated a more neutral or positive topic, but as this space is to chart my journey thru a myriad of topics, most of them technical, the frustrating ones will end up here too.

About 2.5 years ago, I started playing around with a blog on a different domain and with a slightly different focus. I’ve always been fond of the principles around static site generators for a few reasons. One is I love working with text I can punch up easily with markdown in a flat file structure. I spent over a decade as a systems engineer and SRE working with Wordpress and Drupal, and the thought of using anything that complicated for my personal musings and journey brings on the CMS nightmares. Additionally, I hate having my site exist as a space that has anything more complicated than an RSS feed, a list of posts, and an occassional bit of media embedded in a post itself. My inspirations are Dan Luu, Julia Evans, Tracy Chou, and Cory Doctorow. Bastions of minimalism all. The last part I really love about static site generators is the final post artifact is pure good HTML. I’ll admit I’m nostalgic for the simplicity of the mid-to-late 90’s when I first got vast exposure to the tech world at the time, but HTML is portable, simple, and works extremely well for static content.

After researching many tools like Jekyll and Gatsby (how Gatsby markets itself as a “simple site generator” backed by GraphQL and React, I’ll never understand), I landed on Hugo. It’s what I used for my old blog. The theme I used wasn’t supported anymore, so I figured I’d migrate to a new one. And this is where the FUN began. First, I tried re-using the old GitHub repo of my previous blog site and just updating the theme. GitHub submodule navigation adventures aside, I figured: install new theme, update theme name in config.toml (now called hugo.toml) and do a hugo server -D build to examine the newly generated artifacts and go from there. Nope… no such luck. The rendered blog posts continued to show up in the old theme no matter what I did. :/

I was going to migrate everything to a new domain and repo anyways, plus Hugo now has an officially supported GitHub Action to publish to GitHub Pages, so I decided to start from scratch and manually move over the existing blog posts I had on the old site (it was only 4, so it wouldn’t be too much work). I went about setting up the new repo and a fresh Hugo site with a supported minimalist theme with enough simple knobs to tune for my tastes. I re-create the old site posts by using the hugo new content content/posts/some-blog-topic.md command and copy/paste the text from the old Hugo site content .md files. Let’s run hugo server -D and see what we get…a ton of example posts included in the base theme alongside my new posts. It took me a while to figure out that the directory structure of the theme (via git submodule) mirrors the base layout of the Hugo site. I copied over the example files from the theme and started modifying them. AHA! My posts started showing up as an overwrite to the base theme ones. I had to modify every file served from the theme however, including things like footer.md and _index.md or I’d get odd jumble of content. I’m still working thru how to exclude the theme example posts. They still show up when I serve up in Draft form. Since it’s just me running this blog and it’s super simple, I set my next post I’m working on (working with a 1 post per git branch method), and automatically set draft = false and run hugo server. I stumbled upon how to use Hugo modules as an option and then use includeFiles/excludeFiles path based exclusion of the theme… but that would require me to re-init my Hugo project again and I’m not up for it at the moment. If and when I do move in that direction, it’ll be time for another blog post detailing the process.

For now, the site is back up and running using GH actions to deploy. I have a simple and effective way to get my content out without too much hassle. The next step is figuring out embedding audio files.