docguard-structure 0.2.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 (CLI command remains docguard; this is not the unrelated docguard-cli package). Use uv add docguard-structure, then run uv run docguard docs/ --summary. Equivalent with pip: pip install docguard-structure. Git-based install: usage guide — Install from Git.

Configure [tool.docguard] in pyproject.toml using the configuration example. Full install commands, pytest integration, and exit codes: usage guide. To adopt docguard in another repository, see Use in another repository.

docguard docs/ --summary

What this tool checks

Docguard focuses on document structure and repository health. Prose style checks (DG-STYLE001, DG-STYLE002) flag decorative strong emphasis and conversational phrasing in body text; they are not a general Markdown formatter.

Phase	What you can check	Diagnostics	Typical default
Core	Document and section size; typed document shape; index reachability; prose style	DG-SIZE001, DG-SIZE002, DG-FORMAT001, DG-FORMAT003, DG-ORG003, DG-STYLE001, DG-STYLE002	on when configured; prose style warning
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	opt-in, warning

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 (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.

Phase 3 structure diagnostics (DG-SPLIT001, DG-FORMAT002) and prose style diagnostics (DG-STYLE001, DG-STYLE002) are implemented. 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