Internal link validation
Overview
Document authors include links to related content within a project. A link destination might be:
- Another page
- A heading on another page
- A heading on the same page
While useful and necessary for document consumers, internal links are prone to breakage as the project changes over time.
The problem
A link to a heading on another page typically looks something like:
/articles/article-1#section-2
------------------- ---------
path fragmentIf someone changes the path of the target page, or the heading on the target page, they will break the link on the source page.
Example 1: Change the path
| Sequence | Type | Description |
|---|---|---|
| 1 | Thought | This page title is imperfect. |
| 2 | Action | Change the page title. |
| 3 | Thought | The URL doesn’t match the new title. |
| 4 | Action | Change the path to match the new title. |
| 5 | Result | Links to this page are now broken. |
Example 2: Change the heading
| Sequence | Type | Description |
|---|---|---|
| 1 | Thought | This section heading is imperfect. |
| 2 | Action | Change the heading. |
| 3 | Side effect | The id attribute of the HTML heading element changes. |
| 4 | Mistake | Forget to search the site for link fragments pointing to the old heading. |
| 5 | Result | Links to the heading on this page are now broken. |
The solution
Link checkers, both proprietary and open source1, can identify broken links including a fragment, if present. This is a good approach, and required for external link validation, but there is room for improvement:
- When used in CI/CD deployments, link checkers do not identify errors until a document author submits a pull request. This delays error identification and resolution, and requires another round of CI/CD testing.
- When used in development, document authors must (a) install the link checker locally, and (b) remember to periodically run the link checker.
You can address these deficiencies with a link render hook that checks both the path and fragment components of an internal link destination, with no external dependencies.
Hugo introduced the
.Page.Fragmentsstructure in v0.111.0, providing access to the headingidson a page. See the tables of content article for more information.
The example in the link and image render hooks article validates the path and fragment portions of a link destination. If a document author runs hugo server while creating or editing pages, Hugo throws an error or warning (configurable) when rendering a broken link.
Immediate validation improves document quality, reduces CI/CD errors, and decreases time-to-publish.