hugolint CI job: feedback issue

What happened?

hugolint is a CI job that detects broken link in the Handbook.

We are removing the allow_failure: true setting from the hugolint CI job. That means that the hugolint job must now succeed in order to merge an MR. In the past the hugolint job was allowed to fail without blocking the merge.

Why are you doing that?

It is easy to break links in the handbook without even noticing. For example, when you move a page or change a heading you may unknowingly break incoming links. We have put considerable effort in to clean up links in bulk where we can, but there are still almost 4000 broken links in the handbook today. It is a better practice and less effort to prevent breaking links, instead of fixing issues after they have already been merged.

Using the tool

Code quality report

hugolint also creates a "code quality report" which is shown in several places. The most convenient is the MR's "Changes" tag, where the error is shown at the affected line.

Job logs

When the hugolint CI job fails, you can check the its logs to get a list of all broken links it detected. For example:

Newly broken (only in "linkcheck.json", 1 issues):
+ [content/handbook/product/_index.md:16]: <major> Link destination "content/handbook/product/groups/product-technical-program-management.md" does not exist

The most common mistakes and their fixes

We monitored the hugolint job extensively for false positives. In doing so, we have identified the following as the most common mistakes made when creating new links:

content/ as a prefix

Fix: drop the content or /content prefix.

The Handbook's web root is the content/ directory. When creating a link in the Handbook, you have to remove any /content or content prefixes. Most links should start with /handbook/.

handbook/ as a prefix

Fix: add a leading slash, i.e. use /handbook/ instead.

Links that do not start with a slash are relative to the page containing the link. Most links in the handbook should be absolute, that means they should start with /handbook/.

False positives

In rare cases, hugolint mistakenly reports a valid link as broken. This happens primarily when more advanced Hugo features are used, such as shortcodes.

If you encounter such a case, please add a comment to this issue, including a link to the hugolint job reporting the false positive. Once verified, we can exclude that link destination from the check.

Reporting problems

Please use the hugolint issue tracker to report problems with hugolint.