docguard-structure 0.4.0

CLI-first Markdown structure checker for repositories

docguard

CLI-first Markdown structure checker for repositories.

Docguard helps teams keep documentation from growing too large, becoming unreachable from index files, or drifting away from expected document types such as ADRs.

Quick start

Install from PyPI as docguard-structure. The CLI command remains docguard. This is not the unrelated docguard-cli package. Use uv add docguard-structure, then run uv run docguard --summary. Existing uv users can upgrade with uv add --upgrade docguard-structure; see Update an existing uv install. Equivalent with pip: pip install docguard-structure. Git-based install: usage guide — Install from Git.

Run docguard init for a starter [tool.docguard] snippet, or use the strict baseline without configuration. Full install commands, configuration, pytest integration, and exit codes: usage guide. To adopt docguard in another repository, see Use in another repository.

docguard --summary

What this tool checks

Docguard focuses on document structure and repository health. Prose style checks DG-STYLE001 and DG-STYLE002 flag decorative strong emphasis, conversational phrasing, and parenthetical asides in body text. DG-STYLE003 flags forbidden documentation expressions in headings, prose, and table headers. These checks are not a general Markdown formatter.

With no configuration, docguard applies the strict baseline: scan README.md, CONTEXT.md, and docs; require reachability from README.md; enforce 300-line documents, 120-line sections, and a 20-line floor for untyped non-index documents; and fail duplicate guidance plus prose and documentation style diagnostics as errors. Any relaxation from that baseline must be recorded in [[tool.docguard.relaxations]] with a reason.

Phase	What you can check	Diagnostics	Typical default
Core	Document and section size; stub detection; typed document shape; index reachability; prose and documentation style	DG-SIZE001, DG-SIZE002, DG-SIZE003, DG-FORMAT001, DG-FORMAT003, DG-ORG003, DG-STYLE001, DG-STYLE002, DG-STYLE003	strict baseline, error
Phase 2	Link structure between files: orphans and hub dead ends	DG-ORG001, DG-ORG002	opt-in, warning
Phase 3	Structure inside each file: mixed roles and heading level skips	DG-SPLIT001, DG-FORMAT002	opt-in, warning
Duplicate guidance	Repeated commands, list guidance, or prose paragraphs across the scan scope; headings and paragraphs opt-in	DG-SPLIT002	strict baseline, error

Phase 2 details: organization rules. Phase 3 and duplicate guidance details: structure rules. Prose style details: prose style rules. To adopt docguard in another repository, see Use in another repository.

Development

Requires Python 3.11+ and uv on PATH:

uv pip install -e ".[dev]"
uv run pytest
uv run docguard README.md CONTEXT.md docs/ --summary

Documentation

• Usage
• Organization rules (Phase 2)
• Structure rules (Phase 3)
• Prose style rules
• Dogfood and self-test
• Release readiness
• Domain glossary (CONTEXT.md)
• Architecture decision records

Status

Alpha release with Trove classifier Development Status :: 3 - Alpha. Configuration keys, diagnostic JSON fields, and rule defaults may change; breaking changes are recorded in CHANGELOG.md. Exit codes and existing diagnostic meanings are preserved where practical.

Docguard uses a strict baseline by default. Relaxations require [[tool.docguard.relaxations]] entries with reasons. Release readiness is documented in docs/release-readiness.md.

Repository navigation

Relative links for clone checkouts and docguard reachability checks:

• docs/usage.md
• docs/organization-rules.md
• docs/structure-rules.md
• docs/prose-style-rules.md
• docs/dogfood.md
• docs/release-readiness.md
• CONTEXT.md
• docs/adr/0001-cli-first-docguard.md
• docs/adr/0002-structured-diagnostics-and-strict-config.md
• docs/adr/0003-organization-link-rules.md
• docs/adr/0004-utf-8-markdown-encoding.md
• docs/adr/0005-phase3-structure-diagnostics.md
• docs/adr/0006-document-budget-dogfood-gate.md
• docs/adr/0007-document-responsibility-drift-guard.md
• docs/adr/0008-pypi-alpha-distribution.md
• docs/adr/0009-duplicate-guidance-diagnostic.md
• docs/adr/0010-duplicate-guidance-kind-scope.md
• docs/adr/0011-duplicate-prose-paragraph-guidance.md
• docs/adr/0012-prose-style-diagnostics.md
• docs/adr/0013-pypi-distribution-name-docguard-structure.md
• docs/adr/0014-strict-baseline-and-policy-relaxations.md
• docs/adr/0015-forbidden-documentation-expressions.md