vadocs - Documentation Validation Engine

Motivation¶

Documentation-as-Code treats documentation with the same rigor as software: version control, automated testing, CI/CD pipelines, and structured metadata. This approach enables:

• Consistency - Enforced standards across all documents

• Automation - Pre-commit hooks catch issues before merge

• Discoverability - YAML frontmatter enables search, filtering, and index generation

• Quality Gates - CI pipelines validate documentation like code

However, implementing Documentation-as-Code requires validation tooling:

• Is the frontmatter complete and valid?

• Are cross-references (like {term} in MyST) correctly formatted?

• Are required sections present in ADRs?

• Is the index synchronized with individual documents?

vadocs provides this validation infrastructure as a reusable package, eliminating the need to copy scripts between documentation repositories.

Purpose¶

A reusable Python package for validating structured documentation with YAML frontmatter. Extracted from tools/scripts/ per ADR-26012.

Target Users¶

• Documentation maintainers who want automated quality checks

• Teams adopting ADRs (Architecture Decision Records) with structured workflows

• MyST/Jupytext users who need frontmatter and cross-reference validation

• DevOps engineers integrating documentation validation into CI/CD

Scope¶

In Scope¶

• YAML frontmatter validation (required fields, allowed values)

• ADR-specific validation (status, tags, sections, term references)

• Configuration loading from YAML files

• Validator and Fixer base classes for extensibility

Out of Scope¶

• CLI interface (deferred to v0.2.0)

• pyproject.toml [tool.vadocs] config loading (deferred)

• Project scaffolding (vadocs init)

• Link validation (separate concern)

• Jupytext sync (separate concern)

Required Capabilities¶

Core Models¶

• Document - Represents a file with path, content, frontmatter, and doc_type

• ValidationError - Structured error with path, line, error_type, message, suggestion

• SyncField / SyncResult - For bi-directional sync operations

Validators¶

Fixers¶

Configuration¶

• load_config(path) - Load validation rules from YAML file

• Support for: required_fields, valid statuses, valid tags, date format, term reference patterns

Interface Contracts¶

Validator Protocol¶

class Validator(ABC):
    name: str

    def validate(self, document: Document, config: dict) -> list[ValidationError]: ...
    def supports(self, document: Document) -> bool: ...

Fixer Protocol¶

class Fixer(ABC):
    name: str

    def fix(self, document: Document, errors: list[ValidationError], config: dict) -> FixResult: ...
    def supports(self, document: Document) -> bool: ...

Governing ADRs¶

• ADR-26012: Extraction of Documentation Validation Engine (founding document)

• ADR-26001: Use of Python and OOP for Git Hook Scripts

• ADR-26011: Formalization of the Mandatory Script Suite Workflow

• ADR-26020: Hub-and-Spoke Ecosystem Documentation Architecture

Version Roadmap¶

Implementation¶

Repository: packages/vadocs/ (PoC, will move to standalone repo)

Tests: 79 passing

Installation (after move to standalone repo):

uv add "vadocs @ git+https://github.com/<org>/vadocs.git"