DocSprout docs
Browse documentation

Start here

OverviewYour first siteBuild and inspect your siteWrite useful documentationGlossaryTroubleshooting

Shape your site

ConfigurationAuthoring recipesSections and identityCustomize the home pageThemesCustom CSS (advanced)Machine-readable contractsVisual fixturesMathematics

Publish safely

Audit your documentationGitHub PagesPre-publish checklistHistorical documentationQualification evidenceMigration

Pascal and project internals

PasWeave integrationArchitectureArchitecture analysisProject specification (historical)

Project decisions

BoundariesHistory and customisationRelease-tag publicationReader-first documentationLocal syntax highlightingExisting-repository adoptionGitHub Pages setupDocumentation auditSimple configurationv1.0 stable contractDocSprout rebrand

Audit your documentation

Before publishing, run:

docsprout audit

check asks, “Can DocSprout safely build this site?” audit asks, “What objective documentation problems should I fix?” Run check after changing configuration or navigation; use this guide for the audit rules and report formats. Audit is read-only: it never rewrites Markdown, navigation or configuration.

Read the report

Errors describe public links, anchors or local assets that cannot work in the published site. Warnings point out a small number of likely accessibility or structure mistakes. Warnings do not fail the default command:

docsprout audit --strict

Use --strict in a CI job when warnings should also block publication. The exit status is 0 for a successful audit under the selected policy, 1 for findings that fail that policy, and 2 for command or configuration errors.

For tools and CI systems, request deterministic JSON:

docsprout audit --format json

The JSON report is a versioned machine contract: it begins with "schema_version": 1 and then reports pages, errors, warnings and the ordered findings array. See Machine-readable contracts.

What is checked

Audit uses the same configured navigation, root README.md handling and heading IDs as the builder. A Markdown file that exists but is excluded from layout.json is only reported when a published page links to it; drafts are otherwise intentionally quiet.

CodeSeverityMeaning
DK001errorLocal Markdown page link has no target.
DK002errorLink points to an existing Markdown file that is not published.
DK003errorSame-page or cross-page heading anchor is missing.
DK004errorLocal image or asset is missing or outside supported documentation paths.
DK005errorLocal link attempts to escape documentation paths.
DK101warningMarkdown image has empty alternative text.
DK102warningHeading levels skip an intermediate level.
DK103warningTwo headings share the same anchor text; published anchors receive a numeric suffix.

Local Markdown assets are published under the generated site’s content assets directory. External https: URLs are accepted but never network-checked; offline, deterministic builds remain the default.

A small CI gate

Keep the buildability gate and choose the audit policy deliberately:

docsprout check
docsprout audit --strict --format json

Start by fixing errors. Treat warnings as prompts to inspect the document, not as a writing-style score.