Hugo 0.123 behavior change: broken ref/relref are treated as errors, breaking the build
Problem to solve
Hugo 0.123 throws errors with broken refs, reported by @viktomas in Slack.
hugo serve
hugo: collected modules in 1261 ms
Watching for changes in /Users/tomas/{Library,workspace}
Watching for config changes in /Users/tomas/workspace/gl/handbook/config/_default, /Users/tomas/Library/Caches/hugo_cache/modules/filecache/modules/pkg/mod/github.com/google/docsy@v0.9.1/hugo.yaml, /Users/tomas/workspace/gl/handbook/go.mod
Start building sites …
hugo v0.123.4-21a41003c4633b142ac565c52da22924dc30637a+extended darwin/arm64 BuildDate=2024-02-26T16:33:05Z VendorInfo=brew
ERROR [en] REF_NOT_FOUND: Ref "/content/handbook/support/readiness/operations/docs/gitlab/account_deletions.md": "/Users/tomas/workspace/gl/handbook/content/handbook/support/workflows/account_deletion_access_request_workflows.md:26:85": page not found
ERROR [en] REF_NOT_FOUND: Ref "/content/handbook/support/readiness/operations/docs/gitlab/account_deletions.md": "/Users/tomas/workspace/gl/handbook/content/handbook/support/workflows/account_deletion_access_request_workflows.md:101:224": page not found
ERROR [en] REF_NOT_FOUND: Ref "/content/handbook/business-technology/end-user-services/_index.md": "/Users/tomas/workspace/gl/handbook/content/handbook/support/workflows/account_verification.md:24:65": page not found
ERROR [en] REF_NOT_FOUND: Ref "/content/handbook/support/readiness/operations/docs/zendesk/automations.md": "/Users/tomas/workspace/gl/handbook/content/handbook/support/workflows/account_verification.md:59:49": page not found
ERROR [en] REF_NOT_FOUND: Ref "/content/handbook/support/readiness/operations/docs/zendesk/triggers.md": "/Users/tomas/workspace/gl/handbook/content/handbook/support/workflows/account_verification.md:59:153": page not found
ERROR [en] REF_NOT_FOUND: Ref "/content/handbook/about/support.md" from page "/": page not found
ERROR [en] REF_NOT_FOUND: Ref "/content/handbook/about/on-call.md" from page "/": page not found
ERROR [en] REF_NOT_FOUND: Ref "/content/handbook/support/_index.md" from page "/": page not found
@juan-silva was able to address the problem in Slack
- First I had to add the config option
refLinksErrorLevel: WARNING
to/config/_default/config.yaml
this way REF errors do not prevent the build to complete. As a side note, it seems these errors are there because someone successfully pushed changes using broken refs. According to the docs, absolute references should be specified using thecontent
directory as the base. So a reference that specifies /content/handbook…. should be rewritten as /handbook…- Once I get past that I was still having the other errors I posted above. These were because I was missing the data yml files. This was on me, because when I ran
./scripts/synch-data.sh
I didn’t realized that it failed because I was missingwget
in my local computer. Installing wget and running the sync fixed those problems- Finally, I was able to build, but I could not access
localhost:1313
, I then realized that the README states that the container should be run like: `docker run --rm -v ${PWD}:/src -p 1313 --name gl-hugo-exts hugomods/hugo:exts hugo server
, however this does not specify the host computer port, just the internal container port to be exposed. Rewriting this to `docker run --rm -v ${PWD}:/src -p 1313:1313 --name gl-hugo-exts hugomods/hugo:exts hugo server
worked for me. I see that this MR introduced the change in the port parameter.
@dnsmichi upgradeded from Hugo 0.121 to 0.123 and then saw the same behavior.
Handbook Documentation: Docker with Hugo v0.121
The documentation only supports Docker containers for now, until a new maintainer group is formed. Context in https://gitlab.com/gitlab-com/content-sites/handbook#running-hugo and gitlab-com&2281
But they do not show that behavior because the Hugo version is 0.121.2
Hugo 0.123
It seems that the ref error detection was broken before, or had regressions. Not directly visible in the changelog. https://github.com/gohugoio/hugo/releases
Proposal
- Fix the broken URLs in the handbook - thanks @eread !4062 (merged)
- Enable/Update Hugo in CI/CD to error out on broken ref links - related to #202 (closed)
- Figure out if the Docker container in the docs can be updated.
- Update the documentation with the port mapping