Transforming Ripgrep's Documentation with AI Automation and MkDocs

An AI-assisted workflow transforms ripgrep’s documentation from two long files into a structured, 55-page learning and reference resource. The approach replaces mdBook with MkDocs Material, whose features include native Mermaid diagrams, styled admonitions, code annotations, tabs, and stronger search. Before editing, automation analyzes documentation gaps and page structure, then splits oversized chapters at logical headings - for example, a 1,400-line guide became eight basics pages, while binary-data and troubleshooting sections were also divided into focused topics. It scans the filesystem to discover every Markdown file, ensuring newly created pages are not missed. AI agents then review and improve each page individually, fixing outdated information and choosing visual aids suited to its subject.

The workflow’s validation goes beyond checking whether files build. A strict MkDocs build catches structural and syntax problems, while Mermaid-Sonar evaluates diagrams for readability using measures such as node count, branching, density, and layout. It found eight broken diagrams and 12 that were technically valid but too complex, giving agents specific guidance for correction. The completed documentation has seven major sections, 87 diagrams, 358 callouts, and more than 180 annotated code examples, with a successful strict build. The central lessons are that automatic page splitting matters more than decoration, visual features should be chosen with context rather than applied mechanically, and measurable complexity checks help prevent AI-generated material from becoming harder to understand than the text it is meant to clarify.