# Docuchango
[](https://github.com/jrepp/docuchango/actions)
[](https://codecov.io/gh/jrepp/docuchango)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MPL-2.0)
[](https://github.com/astral-sh/ruff)
[](http://mypy-lang.org/)
[](pyproject.toml)
[](https://github.com/jrepp/docuchango/graphs/commit-activity)
[](https://github.com/jrepp/docuchango)
Validate and fix Docusaurus documentation. Checks frontmatter, links, code blocks, and formatting.
```mermaid
flowchart LR
A[docs-cms/] --> B{docuchango}
B -->|validate| C[✓ Report errors]
B -->|fix| D[✓ Fixed docs]
D --> E[Docusaurus]
E -->|build| F[📚 Static site]
style A fill:#f9f,stroke:#333
style B fill:#bbf,stroke:#333
style C fill:#bfb,stroke:#333
style D fill:#bfb,stroke:#333
style E fill:#feb,stroke:#333
style F fill:#bfb,stroke:#333
```
## Quick Start
### 1. Bootstrap a docs-cms Project
```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install docuchango
curl -sSL https://raw.githubusercontent.com/jrepp/docuchango/main/install.sh | bash
# View bootstrap guide
docuchango bootstrap
# View agent instructions
docuchango bootstrap --guide agent
# View best practices
docuchango bootstrap --guide best-practices
```
### 2. Validate and Fix Documentation
```bash
# Validate
docuchango validate
# Fix issues
docuchango fix all
```
## Example Usage
```bash
# Run validation
$ docuchango validate --verbose
📂 Scanning documents...
Found 23 documents
✓ Validating links...
Found 47 total links
❌ DOCUMENTS WITH ERRORS (2):
adr/adr-001.md:
✗ Missing field: 'deciders'
✗ Invalid status: 'Draft'
# Fix automatically
$ docuchango fix all
✓ Fixed 12 code blocks
✓ Removed trailing whitespace
✓ Added missing frontmatter
```
## Document Structure
```text
docs-cms/
├── adr/ # Architecture Decision Records
│ ├── adr-001-*.md
│ └── adr-002-*.md
├── rfcs/ # Request for Comments
│ └── rfc-001-*.md
├── memos/ # Technical memos
│ └── memo-001-*.md
└── prd/ # Product requirements
└── prd-001-*.md
```
Each doc needs frontmatter:
```yaml
---
id: "adr-001"
title: "Use Click for CLI"
status: Accepted
date: 2025-01-26
deciders: Engineering Team
tags: ["cli", "framework"]
project_id: "my-project"
doc_uuid: "..."
---
```
### Schema Structure
```mermaid
graph TD
A[Document] --> B[Frontmatter]
A --> C[Content]
B --> D[Required Fields]
B --> E[Optional Fields]
D --> F[id: adr-001]
D --> G[title: string]
D --> H[status: Literal]
D --> I[date/created]
D --> J[tags: list]
D --> K[project_id]
D --> L[doc_uuid: UUID]
C --> M[Markdown Body]
C --> N[Code Blocks]
C --> O[Links]
style A fill:#bbf,stroke:#333
style B fill:#feb,stroke:#333
style C fill:#bfb,stroke:#333
style D fill:#fbb,stroke:#333
```
**Templates & Docs:**
- [ADR Template](templates/adr-template.md) | [RFC Template](templates/rfc-template.md) | [Memo Template](templates/memo-template.md)
- [Schema Docs](docuchango/schemas.py) | [ADR-001](docs-cms/adr/adr-001-pydantic-schema-validation.md)
## Features
- **Validates** frontmatter (required fields, valid formats)
- **Checks links** (internal, relative, broken refs)
- **Fixes automatically** (whitespace, code blocks, frontmatter)
- **Fast** (100 docs in < 1s)
- **CI-ready** (exit codes, clear errors)
## Commands
```bash
# Validate everything
docuchango validate
# Validate with verbose output
docuchango validate --verbose
# Skip slow build checks
docuchango validate --skip-build
# Fix all issues
docuchango fix all
# Fix specific issues
docuchango fix code-blocks
docuchango fix links
# CLI shortcuts
dcc-validate # Same as docuchango validate
dcc-fix # Same as docuchango fix
```
## Python API
```python
from docuchango.validator import DocValidator
from docuchango.schemas import ADRFrontmatter
# Validate
validator = DocValidator(repo_root=".", verbose=True)
validator.scan_documents()
validator.check_code_blocks()
validator.check_formatting()
# Use schemas
adr = ADRFrontmatter(**frontmatter_data)
```
## Development
```bash
# Setup
uv sync
pip install -e ".[dev]"
# Test
pytest
pytest --cov=docuchango
pytest -n auto # Parallel (for large test suites)
# Lint
ruff format .
ruff check .
mypy docuchango tests
actionlint # Lint GitHub Actions workflows
# Build
uv build
```
## Documentation
- [Templates](templates/) - Starter files for ADR, RFC, Memo, PRD
- [ADRs](docs-cms/adr/) - Architecture decisions
- [RFCs](docs-cms/rfcs/) - Technical proposals
## Requirements
- Python 3.10+
- Works on macOS, Linux, Windows
## License
Mozilla Public License Version 2.0 (MPL-2.0) - See [LICENSE](LICENSE) file
This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.
## Links
- [GitHub](https://github.com/jrepp/docuchango)
- [PyPI](https://pypi.org/project/docuchango)
- [Issues](https://github.com/jrepp/docuchango/issues)
Raw data
{
"_id": null,
"home_page": null,
"name": "docuchango",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "cli, cms, collaboration, documentation, docusaurus, markdown, validation",
"author": null,
"author_email": "Jacob Repp <jacobrepp@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3f/fc/5aaa8f28c1816c6c4b97cd84e9c40351ab21d1b1480b8a1267e99b550c89/docuchango-1.3.0.tar.gz",
"platform": null,
"description": "# Docuchango\n\n[](https://github.com/jrepp/docuchango/actions)\n[](https://codecov.io/gh/jrepp/docuchango)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MPL-2.0)\n\n[](https://github.com/astral-sh/ruff)\n[](http://mypy-lang.org/)\n[](pyproject.toml)\n[](https://github.com/jrepp/docuchango/graphs/commit-activity)\n[](https://github.com/jrepp/docuchango)\n\nValidate and fix Docusaurus documentation. Checks frontmatter, links, code blocks, and formatting.\n\n```mermaid\nflowchart LR\n A[docs-cms/] --> B{docuchango}\n B -->|validate| C[\u2713 Report errors]\n B -->|fix| D[\u2713 Fixed docs]\n D --> E[Docusaurus]\n E -->|build| F[\ud83d\udcda Static site]\n\n style A fill:#f9f,stroke:#333\n style B fill:#bbf,stroke:#333\n style C fill:#bfb,stroke:#333\n style D fill:#bfb,stroke:#333\n style E fill:#feb,stroke:#333\n style F fill:#bfb,stroke:#333\n```\n\n## Quick Start\n\n### 1. Bootstrap a docs-cms Project\n\n```bash\n# Install uv (if not already installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install docuchango\ncurl -sSL https://raw.githubusercontent.com/jrepp/docuchango/main/install.sh | bash\n\n# View bootstrap guide\ndocuchango bootstrap\n\n# View agent instructions\ndocuchango bootstrap --guide agent\n\n# View best practices\ndocuchango bootstrap --guide best-practices\n```\n\n### 2. Validate and Fix Documentation\n\n```bash\n# Validate\ndocuchango validate\n\n# Fix issues\ndocuchango fix all\n```\n\n## Example Usage\n\n```bash\n# Run validation\n$ docuchango validate --verbose\n\n\ud83d\udcc2 Scanning documents...\n Found 23 documents\n\n\u2713 Validating links...\n Found 47 total links\n\n\u274c DOCUMENTS WITH ERRORS (2):\n adr/adr-001.md:\n \u2717 Missing field: 'deciders'\n \u2717 Invalid status: 'Draft'\n\n# Fix automatically\n$ docuchango fix all\n \u2713 Fixed 12 code blocks\n \u2713 Removed trailing whitespace\n \u2713 Added missing frontmatter\n```\n\n## Document Structure\n\n```text\ndocs-cms/\n\u251c\u2500\u2500 adr/ # Architecture Decision Records\n\u2502 \u251c\u2500\u2500 adr-001-*.md\n\u2502 \u2514\u2500\u2500 adr-002-*.md\n\u251c\u2500\u2500 rfcs/ # Request for Comments\n\u2502 \u2514\u2500\u2500 rfc-001-*.md\n\u251c\u2500\u2500 memos/ # Technical memos\n\u2502 \u2514\u2500\u2500 memo-001-*.md\n\u2514\u2500\u2500 prd/ # Product requirements\n \u2514\u2500\u2500 prd-001-*.md\n```\n\nEach doc needs frontmatter:\n```yaml\n---\nid: \"adr-001\"\ntitle: \"Use Click for CLI\"\nstatus: Accepted\ndate: 2025-01-26\ndeciders: Engineering Team\ntags: [\"cli\", \"framework\"]\nproject_id: \"my-project\"\ndoc_uuid: \"...\"\n---\n```\n\n### Schema Structure\n\n```mermaid\ngraph TD\n A[Document] --> B[Frontmatter]\n A --> C[Content]\n\n B --> D[Required Fields]\n B --> E[Optional Fields]\n\n D --> F[id: adr-001]\n D --> G[title: string]\n D --> H[status: Literal]\n D --> I[date/created]\n D --> J[tags: list]\n D --> K[project_id]\n D --> L[doc_uuid: UUID]\n\n C --> M[Markdown Body]\n C --> N[Code Blocks]\n C --> O[Links]\n\n style A fill:#bbf,stroke:#333\n style B fill:#feb,stroke:#333\n style C fill:#bfb,stroke:#333\n style D fill:#fbb,stroke:#333\n```\n\n**Templates & Docs:**\n- [ADR Template](templates/adr-template.md) | [RFC Template](templates/rfc-template.md) | [Memo Template](templates/memo-template.md)\n- [Schema Docs](docuchango/schemas.py) | [ADR-001](docs-cms/adr/adr-001-pydantic-schema-validation.md)\n\n## Features\n\n- **Validates** frontmatter (required fields, valid formats)\n- **Checks links** (internal, relative, broken refs)\n- **Fixes automatically** (whitespace, code blocks, frontmatter)\n- **Fast** (100 docs in < 1s)\n- **CI-ready** (exit codes, clear errors)\n\n## Commands\n\n```bash\n# Validate everything\ndocuchango validate\n\n# Validate with verbose output\ndocuchango validate --verbose\n\n# Skip slow build checks\ndocuchango validate --skip-build\n\n# Fix all issues\ndocuchango fix all\n\n# Fix specific issues\ndocuchango fix code-blocks\ndocuchango fix links\n\n# CLI shortcuts\ndcc-validate # Same as docuchango validate\ndcc-fix # Same as docuchango fix\n```\n\n## Python API\n\n```python\nfrom docuchango.validator import DocValidator\nfrom docuchango.schemas import ADRFrontmatter\n\n# Validate\nvalidator = DocValidator(repo_root=\".\", verbose=True)\nvalidator.scan_documents()\nvalidator.check_code_blocks()\nvalidator.check_formatting()\n\n# Use schemas\nadr = ADRFrontmatter(**frontmatter_data)\n```\n\n## Development\n\n```bash\n# Setup\nuv sync\npip install -e \".[dev]\"\n\n# Test\npytest\npytest --cov=docuchango\npytest -n auto # Parallel (for large test suites)\n\n# Lint\nruff format .\nruff check .\nmypy docuchango tests\nactionlint # Lint GitHub Actions workflows\n\n# Build\nuv build\n```\n\n## Documentation\n\n- [Templates](templates/) - Starter files for ADR, RFC, Memo, PRD\n- [ADRs](docs-cms/adr/) - Architecture decisions\n- [RFCs](docs-cms/rfcs/) - Technical proposals\n\n## Requirements\n\n- Python 3.10+\n- Works on macOS, Linux, Windows\n\n## License\n\nMozilla Public License Version 2.0 (MPL-2.0) - See [LICENSE](LICENSE) file\n\nThis Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.\n\n## Links\n\n- [GitHub](https://github.com/jrepp/docuchango)\n- [PyPI](https://pypi.org/project/docuchango)\n- [Issues](https://github.com/jrepp/docuchango/issues)\n",
"bugtrack_url": null,
"license": "MPL-2.0",
"summary": "Docusaurus validation and repair framework for opinionated micro-CMS documentation, designed for human-agent collaboration workflows",
"version": "1.3.0",
"project_urls": {
"Documentation": "https://github.com/jrepp/docuchango#readme",
"Homepage": "https://github.com/jrepp/docuchango",
"Issues": "https://github.com/jrepp/docuchango/issues",
"Repository": "https://github.com/jrepp/docuchango"
},
"split_keywords": [
"cli",
" cms",
" collaboration",
" documentation",
" docusaurus",
" markdown",
" validation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "327abde14947ed2278005950ad37d72a809ebef903e3f8c399e013821ea3bf16",
"md5": "7a6faf8b915279c59fea84bb4514bb3d",
"sha256": "d1216ed83ca13a480e149936eb4cf753774043752ce6783ced865e8bd983ea5c"
},
"downloads": -1,
"filename": "docuchango-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a6faf8b915279c59fea84bb4514bb3d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 96930,
"upload_time": "2025-10-29T22:29:48",
"upload_time_iso_8601": "2025-10-29T22:29:48.377434Z",
"url": "https://files.pythonhosted.org/packages/32/7a/bde14947ed2278005950ad37d72a809ebef903e3f8c399e013821ea3bf16/docuchango-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3ffc5aaa8f28c1816c6c4b97cd84e9c40351ab21d1b1480b8a1267e99b550c89",
"md5": "ca2634097e921ab7d09a5a84687e713d",
"sha256": "f95de4896e959d4388b4de86611cabece71d58aae4c9768b9668804f0f25ac04"
},
"downloads": -1,
"filename": "docuchango-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "ca2634097e921ab7d09a5a84687e713d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 88703,
"upload_time": "2025-10-29T22:29:50",
"upload_time_iso_8601": "2025-10-29T22:29:50.119179Z",
"url": "https://files.pythonhosted.org/packages/3f/fc/5aaa8f28c1816c6c4b97cd84e9c40351ab21d1b1480b8a1267e99b550c89/docuchango-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-29 22:29:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jrepp",
"github_project": "docuchango#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "docuchango"
}
JSON
