Skip to content

D0021 page-links

Rule: A link between pages is a relative path to a Markdown file that exists.

Code D0021 (stable, never reused)
Id page-links
Category links
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small deny a link to a page that moved or never existed, or to the built site, leads a reader nowhere
small-workspace deny a link to a page that moved or never existed, or to the built site, leads a reader nowhere
medium deny a link to a page that moved or never existed, or to the built site, leads a reader nowhere
big deny a link to a page that moved or never existed, or to the built site, leads a reader nowhere
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Why

Zensical links between pages by the Markdown source's relative path, and rewrites it when it builds the site:

See [the configuration reference](../configuration.md#which-pages).

A link to the built page (configuration.html) or to an absolute path from the site root (/configuration/) works only inside the one book that built it: it breaks once the docs move to another base path, or are read straight from the source tree (a README on GitHub, an AGENTS.md an agent opens by path). zensical build --strict catches a broken link, but only inside a book: a page with no book, or a page a book leaves out of its navigation and no other page links to, gets no check from it.

The lint reads every page the [docs] table selects, book or not. A link that leaves the project (a URL, mailto:, //host) is not judged.

How to fix

Link to the .md file, by a path relative to the page that links it. Drop the .html extension and any leading /. Fix the path, or drop the link, when it does not point at a file that exists.

Configure

[lints.page-links]
level = "deny"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(page-links) <reason> (waivers); the code works there too, as in [lints.D0021].