Lint rules

Nimbus checks content in two ways. Build validators catch what would break a page; they always run and fail the build. Authoring rules catch what renders but shouldn’t ship; they’re off until you turn them on, and nimbus-docs lint runs them. Linting shows how to turn rules on, set their severity per collection, and use --fix.

Build validators

These run during every build and can’t be turned off in the config. To skip one on a single page, use a nimbusDisableRules frontmatter entry or an inline disable comment; see Linting.

nimbus/mdx-syntax

A page’s MDX doesn’t parse, such as an unclosed tag or a stray {.

nimbus/component-pascalcase

A capitalised tag that’s neither registered in src/components.ts nor imported in the page. MDX would print it as text, so the build stops instead.

nimbus/partial-exists

<Render file="…" /> names a partial that doesn’t exist in src/content/partials/.

nimbus/duplicate-slug

Two pages resolve to the same URL.

Authoring rules

Turn these on in rules in the Nimbus integration options, with "error" or "warn". Rules marked fixes itself are applied by nimbus-docs lint --fix.

nimbus/frontmatter-shape

A page’s frontmatter isn’t valid YAML. It reports the parse error before other rules run. The content schema itself, such as unknown keys and wrong types, is checked by the build.

nimbus/description-required

A page has no description, which search results, share cards and agent indexes use. Turn it off for partials with a collection override.

nimbus/internal-link

A link to a page or file on the site that doesn’t exist. It reads the routes from the last build, so run astro build first. Options: ignore (paths to skip), allowRelative, components (extra components whose props hold links).

nimbus/redirected-link

A link that works only through a permanent redirect; the message gives the URL to write instead. Options: ignore, components.

nimbus/image-ref

An image whose file doesn’t exist: a path starting with / is looked up in public/, a relative one next to the page. Options: aliases, ignore, components.

nimbus/single-h1

More than one # heading on a page. The page title already renders as the H1, so a page usually starts at ##.

nimbus/heading-hierarchy

A heading that skips a level, such as an ### straight after an #, which breaks the outline readers and screen readers use.

nimbus/heading-punctuation

A heading that ends in ., ,, :, ; or !. A question mark is allowed. Fixes itself.

nimbus/duplicate-heading-text

Two headings with the same text on one page. Their anchors collide, so links land on the wrong one.

nimbus/code-block-lang

A fenced code block without a language, which loses highlighting and the language badge.

nimbus/code-block-prompt-prefix

A shell code block whose lines start with $ . Readers copy the prompt along with the command.

nimbus/no-self-host-url

A link to the site written as an absolute URL on its own host, such as https://docs.example.com/guide, which breaks on previews. It always flags the configured site and localhost. Option: hosts (other hostnames that are the same site).

nimbus/bare-url

A bare URL in prose, or a link whose text is its URL. Write descriptive link text instead.

nimbus/list-marker-style

A bullet list that uses a different marker from the rest. Option: style, "dash" (default) or "asterisk". Fixes itself.

nimbus/emphasis-style

Italics that use a different delimiter from the rest. Option: style, "asterisk" (default) or "underscore". Fixes itself.

Build and check findings

The build and nimbus-docs check report these codes with the file and the fix. They aren’t lint rules, so they can’t be turned off.

Collection routing

Errors. See Collection URLs.

A page rendered from a route its collection isn’t served from fails the build, naming the route’s folder and the collection’s route file.

On request, such a route returns not found and logs the same advice. Routes under a dynamic folder, such as src/pages/[locale]/kit/[...slug].astro, aren’t reported, since their folder depends on the URL.

Warnings:

Content sources

Warnings from nimbus-docs check. See Content from another repository.

Reserved codes

nimbus/orphan-page and nimbus/sidebar-entry are reserved for future rules. Configuring either as "error" or "warn" stops the build with a message saying so; "off" is accepted.