Ken Muse

My Experience Migrating to Hugo


It’s that time of the season. Just over a year ago, I moved to Piranha for my CMS hosting. At the time, I wanted something quick and easy to setup and didn’t have time to consider Hugo. It’s a year later, and things have changed. Earlier this year, I had to reconsider that decision as I went through the process of upgrading my Piranha install.

Piranha is powerful and easy to use, and I’ve been able to sustain a rather steady amount of traffic with minimal Azure resources (and a little CDN magic). It also uses Markdig, which is definitely my favorite CommonMark compliant Markdown processor. I love the fact that it integrates extensions from GitHub Flavor, PHP Markdown, and Pandoc. This makes it incredibly easy to author content without having to spent my time finding workarounds for missing formatting features. Frankly, it provides me with the best aspects from multiple markdown tools.

Over the last year, I’ve customized Piranha to support my preferred workflow, including using Rick Strahl’s Markdown Monster for editing and publishing. Unfortunately, I spent more time this year trying to improve my workflow than blogging, so a change was definitely needed. As a result, I ended up moving to Hugo and adopting a JAMStack approach. Since everything was already Markdown, migration was a breeze! The most time consuming part was migrating the existing theme from Piranha to Hugo. That meant understanding Hugo’s theme system enough to recreate my ASP.NET MVC layout. Thanks to the power of code with a clean separation of concerns, this took just a few hours.

Creating a development environment for this was easy. I developed the custom theme and tested the site entirely by using DevContainers in Visual Studio Code. My entire development environment was defined as infrastructure-as-code and can be built and tested from within a Docker container. As an added benefit, I can utilize GitHub Codespaces to enable me to author and test my changes entirely in the cloud. I’ve already utilized that a few times to fine-tune the theme.

In terms of functionality, Hugo’s Goldmark Markdown engine may be CommonMark compliant, but it lacks support for most of the extensions I’ve come to appreciate in other systems. Simple things like applying classes or automatically resizing an image using {width=64px} are not yet supported. There was definitely some learning involved since you need to use a smaller subset of Markdown functionality compared to the MarkDig engine that was used in Piranha and Markdown Monster.

To deploy the site, I initially used GitHub Pages. The experience is incredibly simple. That said, I ultimately decided to try out deploying to Azure Static Web Apps. Because my original site was behind Azure Front Door, this made the migration seamless and invisible. There were some challenges with the Onyx engine during builds, but I expect that will improve over time. The site itself required some configuration for Azure SWA using staticwebapp.config.json, but overall the efforts were fairly simple. I added some basic 404 handling and a redirect that ensured my RSS feeds remained intact. In short, a fairly smooth transition.

All of my source code for the site is now moved to GitHub, and GitHub Actions are responsible for the build and deployment of the code. So now, publishing a new post is as simple as committing a Markdown file to a Git repo and completing a pull request. A few minutes later, the updated website is visible to the world. And this post is proof. :-)