Coding Stephan

Blog migrated to hugo on Static Web Apps

The blog you’re currently reading is a written in Markdown, then an application runs and generates static html files. This is called a static site generator, there are several static site generators. Previously I used Jekyll and recently I decided it was time for something new, I migrated to Hugo. Let my explain why I did this and what was needed to make this happen.

Why migrate away from Jekyll

Being a long time Jekyll user, I struggled with the fact that the development-flow was kind of slow. Re-generating the html files took several seconds after a save. And not everything would refresh in the browser immediately. It also required installing Ruby to run locally, or using docker. My Ruby skills are non-existing so whenever if got strange issues involving the Gemfile file, I was stuck for hours.

I heard some good stories about Hugo, and that project has 30% more stars on Github then the former.

Requirements

  • Static site generator
  • Super fast local refresh upon save
  • No complicated dependencies
  • Support for other types (Jekyll supports posts and pages, and that is it)
  • Ability to host on Github Pages and Azure Static Web Apps
  • Tag and category pages without manual labor
  • XML and JSON feed support (I use the json feed to automatically update the posts on my github profile)
  • Light/dark mode support, with toggle

Why a static site generator

Hosting a bunch of html files is much easier than hosting a web application that does dynamic site generation. There is no updating the server (patches/php version) or the application (Wordpress….). When hosting just static files your possibilities are endless, on the other side, if you want for instance use Wordpress (the most popular dynamic site generator) you need a host that supports PHP. And since it’s a web application those hosts cost more money that hosts just serving files.

Since you don’t need compute power to generate the html for each page view, scaling a static site is super easy. You just pay for more bandwidth. Most static websites are also much faster in loading. The client requests a file and gets a response. Versus the client requests a page, the web application has to compute the correct html to send back and the client gets his response.

Not to mention all the security issues with not patching your application/host whenever possible. With a static web site there is no application to hack.

Migrating from Jekyll to hugo

The choice for hugo was made, whats next? To summarize the steps:

  1. Install Hugo winget install Hugo.Hugo.Extended in my case.
  2. Create a new folder
  3. Import old post with hugo import jekyll
  4. Choose a theme for your new hugo website, and configure it.
  5. Run hugo in watch-mode and check the result on your local machine.
  6. Fix all the issues resulting from the import.
  7. Update your Github Actions workflow to deploy the Hugo site instead of Jekyll Azure SWA / Github Pages

Azure Static Web App

Previously this site was hosted at GitHub Pages, a “free” static hosting for all public repositories on GitHub. It’s the go-to host for a lot of tech blogs. I used it for years with a lot of pleasure.

I should be able to host this blog there with ease, but I was also planning to incorporate some “dynamic” features that might require an api. Like search, comments and live chat for during talks. Azure static web apps allows you to host a static website (like this one generated with Hugo), with the ability to have Azure Functions if you need some kind of api.

Combining the two allows you to have the best of both worlds, a super fast static website with some dynamic content where generating static html files is not possible (or the most efficient way).

Dynamic parts

Dynamic parts you say? You just convinced me to go for a static site generator… Yes, dynamic parts. The one thing missing from my static site (with both Jekyll and Hugo) is having a decent super fast search engine. And while you can generate a search index, all those solutions involve a step where you generate a client side search index and some javascript to do the actual search, it all happens in the browser. That means you cannot see what people are looking for and the device has to do the searching. Which might fail on older (phone) devices.

Apart from searching I’m also looking for a privacy friendly way to allow commenting. All solutions I’ve found require at least a cookiebar and/or a special account. And if there is one thing I really don’t like, it’s a cookiebar.

The last planned dynamic feature is allowing some sort of live chat and or polls during talks. That way I could get immediate feedback during or at the end of a live talk. No sure how I’m going to do this but it’s always nice to have something to tinker with in the future.

Migrating host and generator is a bad idea

Looking back on the migration it might had been a better choice to first migrate from Jekyll to Hugo and staying on Github Pages. I had my username github page configured with a custom domain. That meant that all the repositories I had GitHub Pages enabled for where hosted in a folder on my main site. So I had svrooij.io/sonos-api-docs for my unofficial Sonos documentation. This was all managed by GitHub and migrating to hugo and moving the site to Azure Static Web Apps made me need to fix all those redirects at the same time.

If I would do it again, I would separate the migration steps.

How did I fix the issues with all the repositories that where in those folders? I gave all (hopefully) a subdomain so sonos.svrooij.io (still hosted at GitHub Pages), and made a redirect for any requests to those folders if they reach my new Azure Static Web App https://svrooij.io/sonos-api-docs now redirects to the subdomain.

Important if you’re using Github Pages, and you have your {username}.github.io repository with a custom domain, be care full with all the other repositories that also use Github Pages. By default they are hosted under a folder in your custom domain. You can change that, but is requires some planning.

Feedback please

Moving my blog to a new host and a new platform cost some time and productivity, if you have any feedback please let me know. And I’m hoping you follow along with these posts on my journey in migrating my new blog and all the features I might add in the future.

Series: New Blog