What’s the latest version as of writing this post
With version 0.146.0, the Hugo template system was re-architected for very good reasons. This simplifies a lot of things for template lookups. However, there are breaking changes despite the best efforts of the authors. Not all websites and themes that use Hugo, keep up with the pace of Hugo’s development. Many of these projects are open source like Hugo, furthermore many of the maintainers have more than 1 job and aren’t paid to keep their source code up to date.
This blog’s theme is based off of HugoPaperMod. Although I’ve customized several parts of the theme on my blog, the vast majority of it, is still based or the original, which is a big project that has had contributions over several years from several people.
What’s the problem though
I hadn’t published a post in months. So in preparation to create a new post I did what I usually do. I updated my brew packages. Absolutely no reason that you should do this at all. But I have weird habits of keeping things up to date.
I use brew as my package manager as you might already know if you’ve read the post about it.
brew update
I then decided to run hugo and I got the following error!
Error: html/template:_partials/head.html:156:13: no such template "partials/templates/schema_json.html"
This was cryptic to me! I don’t use those files, so must be my theme!
So my instant reaction was update the theme. I installed the theme on this site using Hugo Modules. So the way I get the latest version of the theme is:
hugo mod get -u
This updated the go.mod and go.sum files and I thought I was ready to go.
NO.
It just didn’t help.
What was the fix?
After some mindless searching the web using whatever keywords I could think of at the time, I spotted this issue on Hugo. That was it!
The change in template lookup in 0.146.0 meant anything using PaperMod at this point in time, that was referring to templates in the old-fashioned way, wouldn’t build! You could fix the theme to be compatible with the 0.146.0 of Hugo. But it might be months by the time the pull request for that is accepted.
So my alternative was to use an older version of Hugo, which I deemed was appropriate and easier to do.
How to use an older version of Hugo on MacOS
There are many ways to accomplish this based on how you installed Hugo. The method I’m going to suggest is the one I felt was the simplest.
Get the binary of the older version
You need the binary of the version that you want to go back to. For me it was 0.145.0. You can find the link on the Hugo Releases Page on Github, scroll down to 0.145.0 and expand the Assets to pick the version that’s compatible with your machine architecture. In MacOS this is generally downloaded by default into your ~/Downloads/.
Create a local bin directory
If you haven’t had anything installed locally to override a global installation for your user, maybe you create a local bin directory.
mkdir ~/bin
cd ~/bin
Extract the tar into local bin
Run the tar extract command
tar -xvzf ~/Downloads/hugo_extended_0.145.0_darwin-universal.tar.gz
Update your PATH
On the latest MacOS, you are using ZShell so edit your .zprofile. Add the following to the file.
#override path for older version of hugo
export PATH="$HOME/bin:$PATH"
In case you didn’t already know, $HOME represents ~ or your user’s home directory.
Run the zprofile to export new PATH
source ~/.zprofile
This will get sourced every time you log in.
Verify version
Run hugo version and check it out!
That was it. Now I had the older version that was compatible with my theme! Back to blogging and I made this post, although I came with the intention of writing a completely different one. 🤦.