Downloading my content to get my blog on Micro.blog working with the newest version of Hugo. Very much in my “fuck it, do it live” era. I’ll report back on what I find.

The main issue I’ve run into was the following:

.Site.Author was deprecated in Hugo v0.124.0 and will be removed in Hugo 0.141.0. Implement taxonomy 'author' or use .Site.Params.Author instead.

This is a relatively easy fix– include your .Site.author data in config.json under Params like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "params": {
      "author": {
      "name": "Jason Becker",
      "avatar": "https://micro.blog/jsonbecker/avatar.jpg",
      "username": "jsonbecker",
      "activitypub": {
        "username": "[ACTIVITYPUB_USERNAME]",
        "url": "[ACTIVITYPUB_ACTOR]"
      }
    }
  }
}

Unfortunately, lots of places across Micro.blog templates reference .Site.Author, most especially RSS and JSON feeds.

So in addition to changing references to .Site.author in your own theme (most likely in head.html partials), you’ll have to bring in custom versions of RSS, JSON, and podcast feeds to have a successful site build.

Micro.blog isn’t ready for Hugo 0.140.0 quite yet, but it’s possible to get up and running if you have a custom theme and know how to maintain it. Unfortunately, Hugo doesn’t use semver or anything like it. They also don’t offer stepwise upgrade guides so that you can say, select your current version and the version you want to upgrade to and easily get the steps necessary to keep things working.

There are some nice features that have been added since the last upgrade of Hugo on Micro.blog, but I have to say, the surface of breaking changes that Hugo makes and its impact on themes and plug-ins really feels like a liability. If Hugo followed semver, it’d be a lot easier to maintain versions of themes and plug-ins verified to work at certain markers and maintain older versions as well. As it stands, the upgrade path is kind of rough, and places a lot of burden on a small number of folks.

I’m thinking about if there’s a way that we can incorporate something like the exampleSite process for Hugo as well as some key steps in the Micro.blog process (namely the coalescing of templates and configuration) into a GitHub Actions build step. What I’m imagining is that each theme can have a GitHub Action that builds the exampleSite by coalescing the theme-blank templates and configuration, using reasonable environment variables for some default values that are set on Micro.blog, and then builds against multiple versions of Hugo, generating a check artifact for compatibility. It’s possible even to maintain a release branch for each version of Hugo that is supported by Micro.blog that tests against that version and ensures compatibility.

This way, themes can be updated one version of Hugo at a time, even when Micro.blog doesn’t necessarily support it. Community members can easily generate pull requests that update a theme to a working build on a new version, and maybe the burden can be spread a bit.

With a system like that setup, for example, I suspect it would take me under an hour to get most themes working. Occasionally there’d be a problem that needs a Manton-level fix, but that’d be easy to find. I suspect almost all problems could be solved without Micro.blog official participation provided that theme-blank is used for the coalesce and has a working release that matches the Hugo version. In other words, fixing theme-blank for a version and using that release branch should cover all or nearly all of the Micro.blog-system-level support necessary to fix the downstream themes.

For example, all of the RSS and JSON feed fixes are not needed if theme-blank is updated to use .Site.params.author – except doing so now would break every theme on older versions of Hugo.

The export from Micro.blog has gotten remarkably good. I can fully just run hugo build locally (or hugo server more likely) and get a fully working version of my site, with images, including book covers. This is a testament to @manton’s commitment to data portability.

A little time off from work and I get some progress made on my blog and moved much further down the line on a song I’ve been writing for a couple of months. It’s nice to work to live, without having to give up giving a shit.