Lint rules

Lint rules

The linter reads the whole tree: every page, the navigation, and the five data files. It runs before every commit, in the writer, over MCP, and in your build.

Errors and warnings

An error is a site that would be wrong for a reader. It blocks a commit.

A warning is something to look at. It does not block.

The split is by consequence, not by whether a tool can repair it. A dead anchor cannot be repaired automatically and is only a warning, because the reader still lands on the right page. A dead link is an error, because they land nowhere.

Use --strict to count warnings as failures in a build. Use --advisory to report everything and never fail.

Content

Rule	Severity	What it catches
frontmatter	error	Frontmatter that is not valid YAML or breaks the schema.
missing-title	error	A page with no title.
dead-link	error	An internal link to a page that does not exist.
duplicate-slug	error	Two pages claiming one URL.
missing-asset	error	An image or file reference with nothing behind it.
unsafe-html	error	Raw HTML in a page.
dead-anchor	warning	A link to a heading that does not exist.
not-canonical	warning	Markdown that differs from canonical form.
stray-directive	warning	A directive with the wrong colon count or an unknown name.
undefined-variable	warning	{{name}} with no entry in variables.yaml.
undefined-snippet	warning	::snippet naming a file that does not exist.
wrong-term	warning	A word the glossary rejects.
unknown-owner	warning	An owner who is not a member of the workspace.

Navigation

Rule	Severity	What it catches
nav-invalid	error	nav.yaml breaks the schema.
nav-missing-page	error	The navigation names a page that does not exist.
nav-duplicate	error	A page listed twice.
orphan	error	A page no section lists.

Redirects

Rule	Severity	What it catches
redirects-invalid	error	redirects.yaml breaks the schema.
redirect-loop	error	A chain that returns to its start.
redirect-conflict	error	A redirect and a page claiming one path.
redirect-duplicate	warning	The same from twice.
redirect-chain	warning	A redirect pointing at a redirect.

Data files

Rule	Severity	What it catches
variables-invalid	error	variables.yaml breaks the schema.
glossary-invalid	error	glossary.yaml breaks the schema.
search-invalid	warning	search.yaml breaks the schema.
style-invalid	warning	style.yaml breaks the schema.
search-missing-page	warning	Search tuning naming a page that does not exist.

What --fix repairs

staleless lint --fix rewrites what has a mechanical repair:

• canonical Markdown form;
• a tab, step or card written the short way.

Everything else is reported. A tool that guessed at a dead link would be worse than one that names it.

Where the rules run

Surface	When
The writer	As you edit, and before a commit.
MCP	docs_lint on demand, and inside docs_commit.
Your build	staleless lint, with no network and no token.

The rules are bundled into the command-line tool rather than published beside it, so your build and your workspace can never disagree about what a dead link is.