Skip to main content

Validation Tooling

Summary​

Local validation tooling enforces documentation standards before changes enter a future continuous-integration workflow.

Audience​

  • Documentation authors
  • Documentation reviewers
  • Developers maintaining documentation tooling

Reference Content​

What is validated​

The validators inspect Markdown and MDX files under docs/ for required front matter, metadata types and controlled values, document IDs and slugs, content-type sections, heading structure, internal links, related_docs references, Mermaid fences, and obvious sensitive information. Approved pages also prohibit localhost links and unfinished placeholder tokens. Templates retain metadata, link, general heading, Mermaid, and security validation, while page-type section requirements are deferred until a template becomes an authored page.

Validation commands​

Run all documentation validators:

npm run docs:validate

Run an individual validation area:

npm run docs:validate:frontmatter
npm run docs:validate:structure
npm run docs:validate:links
npm run docs:validate:security

Run the complete local quality gate, including type checking, the production build, and git diff --check when Git is available:

npm run docs:check

Run validator tests:

npm test

Error, warning, and information behavior​

Errors identify violations that block validation and produce a non-zero exit status. Warnings identify reviewable risks but do not fail validation. Informational messages record accepted conditions, such as grandfathered draft placeholders.

Reports include the documentation-relative file path, a line number when practical, a rule identifier, and a concise summary.

Grandfathered placeholders​

The 39 constrained README.md placeholder pages created for the initial information architecture are recognized by their exact section structure. They are reported as informational draft placeholders and do not yet require the complete metadata schema. New pages must not use this exemption.

Local developer workflow​

  1. Create or update documentation using an approved template.
  2. Run the targeted validator while authoring.
  3. Run npm test after changing validator logic.
  4. Run npm run docs:check before requesting review.
  5. Resolve every error and review any warning before approval.

Future CI integration​

A future CI workflow can invoke npm run docs:check as a required quality gate. CI configuration, automated publication, and deployment remain outside the current scope.

See Also​

Keywords​

  • Documentation validation
  • Local quality gate
  • Governance automation

Revision Information​

  • Last reviewed: 2026-07-14
  • Owner: documentation-team
  • Status: Approved