Breaking Changes

I had other plans. Like finalizing some posts I had been mulling over the past days or weeks. But then I did the occasional

brew update && brew upgrade && brew cleanup

And then my blogging process broke. Hugo threw errors¹.

The update to Hugo v146.0 introduced breaking changes. While they claimed to maintain backwards compatibility, that did not seem to work out completely. Hugo did a major overhaul of the template system. Additionally, the themeing situation is a bit messy. There is no default theme, and on the official themes overview site it is not visible at a glance which themes were updated since the last hugo change and which weren’t.

The theme this site uses of course was not updated. Which is what caused most of the errors.

After some digging around, I found that the root cause was a path change when refering to internal shortcodes. In the specific case of the customized figure shortcode, this meant creating a wrapper.

Luckily I found a diff from another theme user and after applying it locally, the build process technically worked again.

I say technically, because a new issue turned up, which was that the taxonomy related pages were empty. Instead of listing all pages per topic, they did show … nothing. And this despite the fact that the term overview page even counted the correct number of posts per term.

I found that, due to the change in folder structure that was part of the template system overhaul, the lookup order for the templates used for the taxonomy list pages changed². Further, I needed to amend the term.htmltemplate. Whereas previously both for terms and the associated pages a list could be generated by looping over .Data.Terms, it now seems that this works only for taxonomy.html. For terms.html I am now looping over the pages instead with

{{ range .Pages }}
	... 
	href="{{ .RelPermalink }}" >{{ .Title }}</a>
	...
	{{ partial "article-meta.html" . }}
	...
{{ end }}

One very handy thing I learned while researching this issue was that

<pre>{{ jsonify (dict "indent" "  ") .Data.Terms }}</pre>

prints the terms variables in a JSON style output. Extremely useful for debugging.

Nevertheless, I have been asking myself if hugo is the right platform going forward. What if next time breaking changes are introduced, they are not so easily fixed? In particular in a theme I did not create myself?