Migrating the Blog to GitHub and Hugo

Ever since I started the blog (two years ago today as it happens!) I’ve been using self-hosted WordPress as my platform of choice. This felt like a no-brainer at the outset - a platform I’d dabbled with in the past and used almost exclusively in the tech blog community. It’s well catered for; there are a multitude of plugins, some well structured and nicely designed themes, and plenty of resources to help you get up and running quickly. For the most part it’s served the purpose well. It’s not without fault though… and for some time now I’ve felt it might be time for a change.

I’ve written a little bit previously about how the site was configured (see here). In summary an Azure App Service, standalone MySQL Azure Database, SendGrid and - more recently - Azure CDN. This latter service has been subject to some change. Initially I served all content via the CDN (as per the blog post), but quickly ran into issues with caching when publishing new content. I eventually settled on a plugin to re-write image and theme URLs to the CDN - meaning generated page content was published direct via the Web App, and heavier content via the CDN. The net result of this was good; minimal maintenance, pretty reasonable performance, and a CMS in WordPress that was intuitive and (generally) reliable…

So why change?

Well… in short, the “good” hasn’t really lasted. I’ve found (increasingly) that site performance is mediocre. Page load times are pretty high (in spite of plenty of grunt on the App Service side), and no matter what database and image optimisation I’ve tried I’ve struggled to get things “snappy”. My Google Analytics stats back this up. WordPress is great, but a little “black box” at times which makes troubleshooting and performance optimsation a pain. Couple that with seemingly endless engine, theme, and plugin updates, and I’ve found I spend more time “tinkering” than I do thinking about content. Enjoyable as that sometimes is (the tinkering, that is!), it isn’t what I set out to do.

Alongside all of the above I’ve been aware that a growing number of sites I follow have been moving to alternative platforms. In many cases, for reasons much like my own.

There’s been a growing “buzz” around static site generators (SSGs) which provide many of the benefits of CMS systems like WordPress (e.g. extensive theme libraries which can be applied “dynamically” to static content), but without the performance or maintenance overhead of a full blown CMS. You’ve likely heard of some of these… Jekyll, Gatsby, and Hugo are some popular examples.

What is a Static Site Generator?

The concept is simple. You input your content - usually in the form of markdown files that define the high level structure and layout - and you process these using your SSG of choice, in accordance with a site configuration file. This configuration file tells your SSG what to do; what theme to apply and how to define certain site settings - date / time format, theme specific variables, and global site information such as the base URL, title, author details and sharing options etc… These options are often theme specific, but highly configurable in much the same way as full blown CMS solutions like WordPress are (albeit via text input, vs. a nice GUI).

The end result is an output folder containing a dynamically generated static site that combines the layout you’ve defined, and the content you’ve created into a flat-file website. Want to write another post? All you need to do is upload a markdown file containing your content to the relevant folder, and reprocess. Upload the output to your hosting platform of choice, and you have a website that has many of the benefits of a dynamic site but coupled with those of a static equivalent… more secure (due to no database), better performing, and next to no “server” maintenance.

What have I done?!

Well, those of you who have visited before will already have noticed that the look and feel is slightly different. No, I haven’t just changed the theme. I’ve gone all in with the static site approach… as of a few days ago this site is no longer built on WordPress. All the content on this site is now generated via Hugo. I’m staggered at the performance improvement and the (relative) simplicity of the transition. Aside from some time tweaking embedded URLs and some formatting oddities of the markdown export tool I used against WordPress, the process couldn’t have been much easier.

It doesnt end there though. The observent of you will have clocked GitHub in the title. Where does that fit?

This, for me, is where the magic of Cloud services comes together. Using SSGs in isolation is quite cool… you can install locally and run the (in my case) Hugo process to generate content from, and to, a local folder. One of the things that tipped my decision to migrate though, was my discovery of the new(ish) Azure Static Web App service. Static Web Apps are a preview feature (and have the advantage of being free - for now) that integrate with GitHub repositories to automate the processing and delivery of web content based on common frameworks or static site generators… Hugo is one of these.

When you deploy a Static Web App, you connect it to a GitHub repository - telling it in the process which deployment framework your source repository uses. This creates an automation workflow in your linked repo, triggered whenever a Git commit is made that reprocesses the contents and uploads the revised content to your Web App. This enables updates from anywhere using a simple git push command! To top things off… you can also commit to a branch, initiate a pull request, and have your “staging” site provisioned into a separate envronment in your Web App. When the pull request is closed and the branch merged with main / master, the staging site is migrated into production. Magic!

I love this new workflow, and increasingly enjoy working with markdown files / git in my local editor… largely as a result of contributing more regularly to Microsoft Docs. There’s something about the simplicity of plain text and the process that feels efficient and (quite ironically) modern. Performance is fantastic, and I have full ability to test and revert changes as and when I need to.

You can read more about the process for integrating Hugo (and others) with GitHub and Azure Static Web Apps here, if interested.

Summary

I still have some work to do on the new format. There are some layout tweaks I want to make and some extensions I’d like to integrate to make interactions (both sharing, and commenting) a bit more “blog like”. Hopefully you’ll agree the new look isn’t too shabby though 👌 There’s no going back for me… What started out as a bit of a learning exercise to get more comfortable with GitHub has become a new way of creating content that I’m super happy with.

I’d encourage those of you wedded to CMS platforms to take a look. It may not be everyone’s cup of tea, but for me it’s a case of goodbye WordPress, long live GitHub and SSG!