Errors while building Hugo site locally

[madebydna]

I tried to set up the Hugo site locally following the instructions in the Contributing guidelines for writers file. I'm currently working on a page with multiple screenshots and thought it would be better to see the page using the site generator rather than using the Markdown preview mode of my IDE.

I installed the hugo executable but wasn't able to build the site and start the server with the make watch command (hugo --bind 0.0.0.0 -p 1313 server --disableFastRender under the hood).

The errors seem to be a mix of content, shortcode and template rendering errors. Before I open an issue I wanted to ask if this is even expected to be working? Also, have others been able to build the site successfully? In that case, the issue could be on my end.

Here is the error output (I replaced the absolute paths with ...):

$ make watch
Hugo is available and has a version greater than 133. Proceeding with build.
hugo --bind 0.0.0.0 -p 1313 server --disableFastRender
hugo: downloading modules …
hugo: collected modules in 14406 msWatching for changes in .../{assets,content,data,layouts,package.json,static}
Watching for config changes in .../config/_default, .../config/development, .../go.mod
Start building sites …
hugo v0.143.0+extended+withdeploy darwin/arm64 BuildDate=2025-02-01T15:56:04Z VendorInfo=brew

ERROR render of ".../content/controller/analytics/catalogs/metrics.md" failed: ".../layouts/ctlr-eos/single.html:29:7": execute of template failed: template: ctlr-eos/single.html:29:7: executing "main" at <.Content>: error calling Content: ".../content/controller/analytics/catalogs/metrics.md:14:1": failed to render shortcode "metrics": failed to process shortcode: "/Users/asingh/Library/Caches/hugo_cache/nginx-documentation/filecache/modules/pkg/mod/github.com/nginxinc/[email protected]/layouts/shortcodes/metrics.html:6:10": execute of template failed: template: shortcodes/metrics.html:6:10: executing "shortcodes/metrics.html" at <.Err>: can't evaluate field Err in type resource.Resource
ERROR render of ".../content/ngf/get-started.md" failed: "/Users/asingh/Library/Caches/hugo_cache/nginx-documentation/filecache/modules/pkg/mod/github.com/nginxinc/[email protected]/layouts/_default/single.html:1:3": execute of template failed: template: _default/single.html:1:3: executing "_default/single.html" at <.Render>: error calling Render: failed to execute template _default/docs.html: "/Users/asingh/Library/Caches/hugo_cache/nginx-documentation/filecache/modules/pkg/mod/github.com/nginxinc/[email protected]/layouts/_default/docs.html:21:7": execute of template failed: template: _default/docs.html:21:7: executing "main" at <.Content>: error calling Content: ".../content/ngf/get-started.md:213:1": failed to render shortcode "ghcode": failed to process shortcode: "/Users/asingh/Library/Caches/hugo_cache/nginx-documentation/filecache/modules/pkg/mod/github.com/nginxinc/[email protected]/layouts/shortcodes/ghcode.html:4:10": execute of template failed: template: shortcodes/ghcode.html:4:10: executing "shortcodes/ghcode.html" at <.Err>: can't evaluate field Err in type resource.Resource
Built in 1960 ms
Error: error building site: render: failed to render pages: render of ".../content/controller/analytics/catalogs/dimensions.md" failed: ".../layouts/ctlr-eos/single.html:29:7": execute of template failed: template: ctlr-eos/single.html:29:7: executing "main" at <.Content>: error calling Content: ".../content/controller/analytics/catalogs/dimensions.md:15:1": failed to render shortcode "dimensions": failed to process shortcode: "/Users/asingh/Library/Caches/hugo_cache/nginx-documentation/filecache/modules/pkg/mod/github.com/nginxinc/[email protected]/layouts/shortcodes/dimensions.html:6:10": execute of template failed: template: shortcodes/dimensions.html:6:10: executing "shortcodes/dimensions.html" at <.Err>: can't evaluate field Err in type resource.Resource: Resource.Err was removed in Hugo v0.141.0 and replaced with a new try keyword, see https://gohugo.io/functions/go-template/try/
make: *** [watch] Error 1

[mjang]

Hi @madebydna

Bottom line: we use Hugo version v0.134.2

• As shown in https://github.com/nginx/documentation/blob/main/CONTRIBUTING_DOCS.md
• That page includes a link to https://github.com/gohugoio/hugo/releases/tag/v0.134.2, from where I downloaded that version of Hugo. Take care to install the version associated with your hardware/operating system

If I'm reading your error message correctly, you're on a Mac with an ARM CPU (your error message includes darwin/arm64)

• If not, I think there are downloads that work for Linux on ARM.

FYI, I was able to replicate your error on a Mac M3 with the following commands:

cd /path/to/documentation_repo
brew install hugo
make watch

Unfortunately, that installs Hugo version v0.143.1. (which you can confirm with the hugo version command) And we have not updated our themes for that version of Hugo.) Your error message suggests that you're running Hugo version v01.43.0..

To get to Hugo version v0.134.2, here's what I did

• Ran brew uninstall hugo
• Downloaded hugo_extended_0.134.2_darwin-universal.tar.gz
• Installed from the CLI (tar xzvf hugo_extended_0.134.2_darwin-universal.tar.gz)
• Copied the hugo binary to /usr/local/bin
• Confirmed my Hugo version (hugo version)
• Navigated to the documentation repo
• Ran make watch

Let me know if that works 🤞

[madebydna]

@mjang yes, thank you, this worked!

I did indeed miss the fact that I needed to install a particular version. I can now see that the guide mentions it. I simply followed the link to the Installing Hugo page. 😅

In any case, I can now access the site at localhost:1313 🎉