Linting Rules

Documentation linting rules and diagnostics.

Agent output#

These rules check the portable Markdown delivered to agents. They flag empty output, oversized pages, and unclosed code fences that disrupt exported content.

Rule	Checks	Severity	Default	Autofix
`agent-page-too-large`	An agent-visible page exceeds the configured portable Markdown size in UTF-8 bytes.	Tip	`{"max":100000}`	-
`empty-portable-markdown`	An agent-visible page produces empty portable Markdown.	Tip	`true`	-
`portable-markdown-unclosed-fence`	An agent-visible page has an unclosed code fence in its portable Markdown.	Warning	`true`	-

Content#

These rules check content length, repeated pages, and image alternative text. They highlight content that needs more detail, clearer sections, or a narrower focus.

Rule	Checks	Severity	Default	Autofix
`code-block-too-long`	A code block exceeds the configured line limit.	Tip	`{"max":100}`	-
`duplicate-page-content`	Pages in the same locale and version have identical non-empty portable Markdown after normalizing line endings and surrounding whitespace.	Tip	`true`	-
`image-missing-alt`	An image omits alternative text. An explicit empty alt is accepted for decorative images.	Tip	`true`	-
`long-unsectioned-content`	The page has too many prose words without section headings.	Tip	`{"max":400}`	-
`section-too-long`	A section exceeds the configured prose word limit.	Tip	`{"max":300}`	-
`thin-content`	The page has fewer prose words than the configured minimum.	Tip	`{"min":100}`	-

Discovery#

These rules check how readers and agents discover the documentation. They flag isolated pages and missing discovery files for public agent endpoints.

Rule	Checks	Severity	Default	Autofix
`agent-catalog-missing`	Public agent endpoints have no AI catalog listing the MCP server and skills. Checked by brief check for generated-style Next applications with a public llms.txt route.	Tip	—	-
`agent-mcp-card-missing`	A public MCP endpoint has no server discovery card. Checked by brief check for generated-style Next applications with public llms.txt and MCP routes.	Tip	—	-
`orphan-page`	A public, search-engine-visible page has no incoming documentation links and is not an entry point or explicitly exempt.	Tip	`true`	-
`unreachable-page`	A public, search-engine-visible page has incoming links but cannot be reached from the documentation entry points and is not explicitly exempt.	Tip	`true`	-

Headings#

These rules check heading text and hierarchy, including the rendered page title. They flag empty or repeated headings and skipped levels that hinder navigation.

Rule	Checks	Severity	Default	Autofix
`duplicate-heading`	A heading repeats on the same page after normalizing whitespace and case.	Tip	`true`	-
`heading-empty`	A heading has no text.	Tip	`true`	-
`heading-level-skipped`	A heading skips a level in the document hierarchy, accounting for the page title heading.	Tip	`true`	-
`multiple-h1`	More than one level-one heading is rendered, including the page title supplied by the site.	Tip	`true`	-

Links#

These rules check link labels, destinations, fragments, and protocols. They flag broken links, historical redirects, version mismatches, and insecure external URLs.

Rule	Checks	Severity	Default	Autofix
`broken-anchor`	An internal link fragment does not match a heading on its target page.	Warning	—	Rewrite the fragment to a suggested heading when a close match exists. Dangerous
`broken-link`	An internal link does not match a published page.	Warning	—	Rewrite the link to a suggested page when a close match exists, preserving its query and fragment. Dangerous
`generic-link-text`	Link text is too generic to identify its destination.	Tip	`true`	-
`insecure-external-link`	An external link uses HTTP rather than HTTPS.	Tip	`true`	-
`link-to-broken-page`	An internal link targets a page that exists but could not be published.	Warning	—	-
`link-to-redirect`	An internal link targets a historical redirect rather than the current destination.	Tip	`true`	Rewrite the link to its final destination, preserving the query and fragment when the fragment is valid.
`link-version-mismatch`	An internal link targets another version even though an equivalent page exists in the current version. Deliberately allowed cross-version links are excluded.	Tip	`true`	-

Localization#

These checks identify missing translations and localized URL slugs. They show where readers receive another language instead of the intended locale.

Rule	Checks	Severity	Default	Autofix
`missing-translation`	A page has no translation for a supported locale, so readers receive the default locale.	Warning	—	-
`untranslated-slug`	A localized page URL falls back to another language's slug.	Warning	—	-

Metadata#

These rules check titles, descriptions, and public URLs. They flag unsuitable lengths, repeated metadata, and URL collisions that prevent compilation.

Rule	Checks	Severity	Default	Autofix
`description-too-long`	The page description exceeds the configured character maximum.	Tip	`{"min":70,"max":160}`	-
`description-too-short`	The page description is shorter than the configured character minimum.	Tip	`{"min":70,"max":160}`	-
`duplicate-page-description`	Pages in the same locale and version share a description after normalizing whitespace and case.	Tip	`true`	-
`duplicate-page-title`	Pages in the same locale and version share a title after normalizing whitespace and case.	Tip	`true`	-
`duplicate-url`	Two published pages claim the same public URL. Compilation stops until the collision is resolved.	Critical	—	-
`title-too-long`	The page title exceeds the configured character maximum.	Tip	`{"min":15,"max":60}`	-
`title-too-short`	The page title is shorter than the configured character minimum.	Tip	`{"min":15,"max":60}`	-
`url-too-long`	The public page URL exceeds the configured character limit.	Tip	`{"max":100}`	-

These checks identify navigation entries and groups that cannot appear as authored. They flag missing children and groups with no published pages.

Rule	Checks	Severity	Default	Autofix
`empty-group`	A group has no published pages and is omitted from navigation.	Warning	—	-
`order-references-missing`	A navigation order entry does not match any child directory.	Warning	—	-

Publishing#

These checks compare authored content and routes with their saved publication checkpoints. They flag stale page update metadata and unrecorded routing changes.

Rule	Checks	Severity	Default	Autofix
`redirects-out-of-sync`	Routing changes have not been synchronized with the committed redirect history.	Warning	—	-
`updated-at-out-of-sync`	A page has no complete update checkpoint, or its body has changed since the recorded checkpoint.	Warning	—	-

Redirects#

These checks validate historical URLs and their destinations. They flag loops, conflicting targets, and redirects that hide pages or lead nowhere.

Rule	Checks	Severity	Default	Autofix
`redirect-conflict`	A redirect source URL has multiple destinations.	Warning	—	-
`redirect-cycle`	A redirect enters a loop instead of reaching a destination.	Warning	—	-
`redirect-self`	A redirect points to its own source URL.	Warning	—	Remove authored self-redirect aliases when the source supports metadata edits.
`redirect-shadows-page`	A redirect source URL is also a published page's URL.	Warning	—	-
`redirect-target-missing`	A redirect does not resolve to a published page.	Warning	—	-

SEO#

These checks validate canonical URLs used by search engines. They flag invalid schemes, fragments, cycles, missing targets, and targets excluded from indexing.

Rule	Checks	Severity	Default	Autofix
`canonical-cycle`	Internal canonical URLs form a cycle.	Warning	—	-
`canonical-has-fragment`	A canonical URL contains a fragment instead of identifying the whole page.	Warning	—	Remove the fragment from the canonical URL.
`canonical-invalid-scheme`	A canonical URL uses a protocol other than HTTP or HTTPS.	Warning	—	-
`canonical-target-missing`	An internal canonical URL points to a page that does not exist.	Warning	—	-
`canonical-target-noindex`	An indexable page canonicalizes to a page excluded from search engine indexing.	Warning	—	-

Configuration#

Set quality rules under contentQuality.rules in the compiler configuration. Use false to disable a quality rule or true to use its default. Setting names match diagnostic codes except for these shared settings:

title-too-short uses title-length.
title-too-long uses title-length.
description-too-short uses description-length.
description-too-long uses description-length.

Diagnostics showing — under Default have no setting in contentQuality.rules. Their severity and execution scope are fixed.