Issues building website locally / possible fixes

[nikclayton]

I was drafting a Pachli blog post for Nivenly, forked the website repo, cloned my fork locally, and bumped into some roadblocks. I'm documenting them here so someone better informed about Hugo than I am can update the docs.

Background

I was installing on a Mac. Following the docs I installed Homebrew, then used Homebrew to install Go and Hugo.

Needs NPM

Running make hugo runs npm ci. NPM wasn't installed, so this errored out.

I fixed this with brew install npm, but I'm not sure if NPM is intended as a dependency, or if it should automatically have been installed.

Needs module updates

After installed NPM and running make hugo again I saw a build error referencing google_analytics_async.html. Some searching lead me to https://discourse.gohugo.io/t/build-error-on-v0-125-2-calling-internal-template-internal-google-analytics-async-html/49410, and this appears to be because of outdated Hugo modules; specifically the docsy module.

The docsy module was at version 0.6.0. Running hugo mod get -u updated it. This also updated Fontawesome and twbs, the go.mod diff is:

 require (
-	github.com/FortAwesome/Font-Awesome v0.0.0-20220831210243-d3a7818c253f // indirect
-	github.com/google/docsy v0.6.0 // indirect
-	github.com/google/docsy/dependencies v0.6.0 // indirect
-	github.com/twbs/bootstrap v4.6.2+incompatible // indirect
+	github.com/FortAwesome/Font-Awesome v0.0.0-20240402185447-c0f460dca7f7 // indirect
+	github.com/google/docsy v0.10.0 // indirect
+	github.com/google/docsy/dependencies v0.7.2 // indirect
+	github.com/twbs/bootstrap v5.3.3+incompatible // indirect
 )

Hugo wants to write somewhere it doesn't have permission

After fixing that and running make hugo again I got:

Error: error copying static files: open /Users/nik/projects/nivenly-website/public/js/tabpane-persist.js: permission denied

(my fork of the website repo is nivenly-website).

This isn't a very helpful message. It's not trying to write to that file, it's trying to copy it somewhere else. I couldn't convince Hugo to tell me where it was trying to copy it to, so I gave up and stuck publishDir = out in config.toml.

Large images

This was enough to get make hugo and then hugo serve to work properly (side note: hugo serve might be the better command to mention for local development, since it reloads-on-save).

For some reason (which I have not debugged) opening the local copy of the site showed the project images on the homepage at their full size, not the smaller size they appear at nivenly.org. There's no errors in the console, and the network inspector didn't show any requests (e.g., to a CSS file that might set the image sizes) that failed.