Hugo Update
The build pipeline for this site recently failed so I had to work out why and learn about updating Hugo sites.
I recently wrote my yearly Advent of Code post, committed it to git and pushed to GitHub only to have the build pipeline that triggers, fail:
The errors are around the use of deprecated functionality in the clarity theme. I found this odd because the theme was updated 2 months ago and is regularly updated by the author. This got me thinking that there must be something in the build process that is resulting in an old version of the theme being used, but why didn’t the build fail for me locally.
1. Updating Hugo
My first check was to see which version of Hugo I had installed locally:
1╰─❯ hugo version
2hugo v0.124.1+extended+withdeploy darwin/arm64 BuildDate=2024-11-23T15:33:51Z VendorInfo=brew
Here we can see the Hugo version is 0.124.1. The Hugo GitHub tagged versions showed the latest version as 0.139.2. From the build failure in GitHub I could see that 0.139.2 was the version being used by the pipeline so the first step was to get Hugo up to date, this is done using Homebrew:
1╰─❯ brew upgrade hugo
2==> Downloading https://formulae.brew.sh/api/formula.jws.json
3############################################################################################################################# 100.0%
4==> Downloading https://formulae.brew.sh/api/cask.jws.json
5############################################################################################################################# 100.0%
6==> Upgrading 1 outdated package:
7hugo 0.124.1 -> 0.139.2
8==> Downloading https://ghcr.io/v2/homebrew/core/hugo/manifests/0.139.2
9############################################################################################################################# 100.0%
10==> Fetching hugo
11==> Downloading https://ghcr.io/v2/homebrew/core/hugo/blobs/sha256:d0785d59bbd09092f57dc8fd8a8ed1ed092a48ee80f93298974e3c70a141b0f8
12############################################################################################################################# 100.0%
13==> Upgrading hugo
14 0.124.1 -> 0.139.2
15==> Pouring hugo--0.139.2.arm64_sonoma.bottle.tar.gz
16==> Caveats
17zsh completions have been installed to:
18 /opt/homebrew/share/zsh/site-functions
19==> Summary
20🍺 /opt/homebrew/Cellar/hugo/0.139.2: 53 files, 68.9MB
21==> Running `brew cleanup hugo`...
22Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP.
23Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).
24Removing: /opt/homebrew/Cellar/hugo/0.124.1... (50 files, 80.5MB)
Now Hugo was up to date locally, I ran the build again:
1╰─❯ hugo --minify
2Start building sites …
3hugo v0.139.2+extended+withdeploy darwin/arm64 BuildDate=2024-11-23T15:33:51Z VendorInfo=brew
4
5WARN deprecated: resources.ToCSS was deprecated in Hugo v0.128.0 and will be removed in a future release. Use css.Sass instead.
6ERROR deprecated: .Site.IsMultiLingual was deprecated in Hugo v0.124.0 and will be removed in Hugo 0.140.0. Use hugo.IsMultilingual instead.
7ERROR render of "page" failed: "/Users/andrew.fitzpatrick/Library/Caches/hugo_cache/modules/filecache/modules/pkg/mod/github.com/chipzoller/hugo-clarity@v0.0.0-20220211152242-d9bf479a91bc/layouts/_default/single.html:45:10": execute of template failed: template: _default/single.html:45:10: executing "main" at <partial "comments" .>: error calling partial: "/Users/andrew.fitzpatrick/Library/Caches/hugo_cache/modules/filecache/modules/pkg/mod/github.com/chipzoller/hugo-clarity@v0.0.0-20220211152242-d9bf479a91bc/layouts/partials/comments.html:2:13": execute of template failed: template: partials/comments.html:2:13: executing "partials/comments.html" at <.Site.DisqusShortname>: can't evaluate field DisqusShortname in type page.Site
8Total in 1115 ms
9Error: error building site: render: failed to render pages: render of "page" failed: "/Users/andrew.fitzpatrick/Library/Caches/hugo_cache/modules/filecache/modules/pkg/mod/github.com/chipzoller/hugo-clarity@v0.0.0-20220211152242-d9bf479a91bc/layouts/_default/single.html:45:10": execute of template failed: template: _default/single.html:45:10: executing "main" at <partial "comments" .>: error calling partial: "/Users/andrew.fitzpatrick/Library/Caches/hugo_cache/modules/filecache/modules/pkg/mod/github.com/chipzoller/hugo-clarity@v0.0.0-20220211152242-d9bf479a91bc/layouts/partials/comments.html:2:13": execute of template failed: template: partials/comments.html:2:13: executing "partials/comments.html" at <.Site.DisqusShortname>: can't evaluate field DisqusShortname in type page.Site
Now the build fails with the same reason as the GitHub pipeline.
2. Updating the Clarity theme
Now that I’m at a point where my local build fails for the same reason as the pipeline I needed to find the reason why. All the issues seemed to be related to the clarity theme, as I said previously this seemed odd as it’s a well maintained theme. The thing I did notice in the output was the hugo-clarity@v0.0.0-20220211... tags, this shows that the version of the hugo-clarity theme I’m using was 2.5 years old. After a bit of scanning around the repo for my Hugo site, I found that this tag was present in the go.sum file.
In Hugo Theme Change I discussed the ways to set up Hugo to use modules. This piece of setup was good at the time but it looks like my Hugo site needed updating to use the latest view of the theme. It took a little bit of investigation and doc reading to understand how the modules Hugo uses are updated. Ultimately the answer lay with a CLI command:
1╰─❯ hugo mod get
2go: downloading github.com/chipzoller/hugo-clarity v0.0.0-20240923132253-174a5e638704
3go: upgraded github.com/chipzoller/hugo-clarity v0.0.0-20220211152242-d9bf479a91bc => v0.0.0-20240923132253-174a5e638704
After running the mod get command I tried another --minify and this time the build completed with success.
1╰─❯ hugo --minify
2Start building sites …
3hugo v0.139.2+extended+withdeploy darwin/arm64 BuildDate=2024-11-23T15:33:51Z VendorInfo=brew
4
5WARN Raw HTML omitted while rendering "/"; see https://gohugo.io/getting-started/configuration-markup/#rendererunsafe
6You can suppress this warning by adding the following to your site configuration:
7ignoreLogs = ['warning-goldmark-raw-html']
8Total in 1350 ms
My final step was to remove the old entry for the hugo-clarity theme from my go.sum file, this was achieved with another CLI command:
1╰─❯ hugo mod tidy
Everything was then committed to Git and pushed to GitHub where the build once again went green.
Avoiding this in future
This blog is a site that attracts sporadic attention from me and it’s the build artefacts that get deployed to GitHub for hosting. If this repository is broken then the public view won’t be broken until I fix the source code. For these reasons I would like to ensure that whenever I write a new post and commit, there will be a build process that is followed. The outcome from the build process should be that the local dependency versions are equal to or later than the ones used on the build server.
One option that I think will work well for this is to use husky. I’ve used this before during AoC 2023 and found it to be a good alternative to pre-commit. The power I have with husky is that I can extend it with scripts very easily. Setting husky up is simple, in my Hugo source repo I did the following.
Init npm within the project
1╰─❯ npm init
In the created package.json file, I added a new script called update, this means that I can easily update huge and the modules that I am using in the Hugo site:
1{
2 ...
3 "scripts": {
4 "update": "brew upgrade hugo && hugo mod get && hugo mod tidy"
5 }
6 ...
7}
Next I added husky as a dev dependency so that it can be triggered on commit.
1╰─❯ npm install --save-dev husky
Initialise husky
1╰─❯ npx husky init
Once husky is initialised a .husky/pre-commit file will be created, in here I add the following:
1# nuke the public directory first
2rm -rf public
3
4# run a build to build the site
5npm run build
Now, whenever I commit to git any pre-build site will be deleted and regenerated as part of my usual workflow, and if I need to update my site I can run npm run update.