探How 社区

来源标题：Transforming Ripgrep's Documentation with AI Automation and MkDocs

Glen Baker 利用 AI 自动化工作流和 MkDocs 将 ripgrep 的文档从两个文件扩展为完整文档站。核心改动包括用 MkDocs 替代 mdBook、智能拆分页面、自动发现页面、逐页增强视觉内容，以及用 Mermaid-Sonar 校验图表复杂度。该工作流强调按页处理优于批量处理，并建议从 MkDocs Material 起步逐步迭代。

以下正文由 AI 翻译自 Hacker News 最新（原文版权归原站所有），可能存在偏差，重要内容请以原文为准。

工程 Prodigy 文档自动化 Mkdocs AI 工作流 Ripgrep 开源作者 Glen Baker 构建科技初创公司与开源工具目录从两个文件到全面文档变化之处：MkDocs 与 mdBook 对比增强后的工作流架构四项关键创新1. 智能页面拆分 2. 穷尽式页面发现 3. 逐页视觉增强 4. 使用 Mermaid-Sonar 验证 Mermaid 图表实际成果：ripgrep 文档改造示例：模式匹配页面的改造关键洞察1. 页面拆分释放全面文档能力 2. 视觉特性需要智能驱动 3. 复杂度校验能抓住 AI 的过度设计 4. 逐页增强优于批量处理三代工作流对比如何套用这套工作流1. 从 MkDocs Material 起步 2. 构建自动发现机制 3. 编写增强逻辑 4. 加入多层校验 5. 迭代与打磨未来增强方向结论资源目录从两个文件到全面文档变化之处：MkDocs 与 mdBook 对比增强后的工作流架构四项关键创新1. 智能页面拆分 2. 穷尽式页面发现 3. 逐页视觉增强 4. 使用 Mermaid-Sonar 验证 Mermaid 图表实际成果：ripgrep 文档改造示例：模式匹配页面的改造关键洞察1. 页面拆分释放全面文档能力 2. 视觉特性需要智能驱动 3. 复杂度校验能抓住 AI 的过度设计 4. 逐页增强优于批量处理三代工作流对比如何套用这套工作流1. 从 MkDocs Material 起步 2. 构建自动发现机制 3. 编写增强逻辑 4. 加入多层校验 5. 迭代与打磨未来增强方向结论资源从两个文件到全面文档

ripgrep 是最受欢迎的命令行搜索工具之一，在 GitHub 上拥有超过 57,000 颗星。尽管它广受欢迎、功能丰富，但文档却只有两个文件：一个侧重功能的 README 和一个教程风格的 GUIDE。这两个文件写得不错，但仍留有空白：使用我文档自动化工作流的进化版本（最初是为 Prodigy 的文档构建的），我生成了 50 多页增强文档，现已上线于 https://iepathos.github.io/ripgrep。本文记录了这套工作流如何演进以应对：最初的工作流使用 mdBook，这是 Rust 生态中流行的一款简单静态站点生成器。MkDocs Material 提供的功能要多得多： ripgrep 的工作流在以往迭代基础上引入了关键改进。完整流程如下：突破性功能：基于结构分析的自动页面拆分。最初的 GUIDE.md 超过 1,400 行——一大堵文字墙。现在工作流会在处理前分析页面结构，并基于以下依据自动将超大页面拆分为聚焦的子页面：页面拆分创建新文件后，我们通过直接扫描文件系统确保每个页面都被处理： find $DOCS_DIR -name "*.md" -type f | jq -R -s 'split("\n") | map(select(length > 0)) | ...' 这一点至关重要，因为：修正偏移之后，每个页面在 map 阶段（而非 reduce 阶段）得到增强，这意味着每个 agent 都完整了解该页面涵盖的内容： AI 会尝试做出上下文感知的决策：“模式匹配决策密集，加一棵决策树。安装方式因平台而异，用标签页内容。” 当你自动生成几十张 Mermaid 图表时，有些会有语法错误，还有很多会复杂到无法阅读。工作流中原本简单的语法校验步骤，最终演变成了一个独立工具：mermaid-sonar。演进过程：最初，工作流使用 @mermaid-js/mermaid-cli 在构建前捕获语法错误。但我注意到一个规律：AI agent 会创建语法上有效、但认知上令人不堪重负的图表。一个二元选择配一棵 80 节点的决策树。一个 3 项列表配一张复杂的流程图。图表渲染正确，却损害了理解。仅靠语法校验还不够。我需要复杂度校验来引导 AI 生成可读的图表。 Mermaid-sonar 使用静态代码分析和有研究依据的启发式规则来衡量图表复杂度，并向 AI agent 提供可操作的反馈：

shell: "mermaid-sonar $DOCS_DIR --strict" on_failure: claude: "/prodigy-fix-mermaid-diagrams ${shell.output}" 它对 AI 工作流有效的原因：这次校验在 ripgrep 文档中抓出了 8 张会在构建时失败的损坏图表，另有 12 张过于复杂、需要简化的图表。关键洞察：AI agent 需要量化反馈才能理解“过于复杂”。通过将主观的可读性转化为带有明确阈值的可度量指标，mermaid-sonar 引导 AI 生成真正帮助读者、而非压垮读者的图表。这就是“捕获错误”与“引导质量”之间的差别。传统校验告诉你哪里坏了。基于启发式规则的校验告诉你哪里需要改进、以及如何改进——这是 AI agent 能够自动据以行动的反馈。改造前（来自 GUIDE.md）：用纯文本解释正则与字面量模式的差异，内容散落在多个章节中。新增决策树图表，帮助用户在字面量模式与正则模式之间做选择；将重要提示改为带样式的 admonition（关于何时使用 -F 标志的提示）；并用带编号的标注注释代码示例，解释每个标志的用途。这个页面从“文字墙”变成了“引导式学习”。最具影响力的创新并非视觉增强——而是自动页面拆分。没有读者愿意滚动 1,400 行去找关于大小写敏感的信息。工作流通过以下方式自动处理拆分：

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）

正文由探How 从来源站点 RSS 同步，内容未经改写；遇到排版缺失或需要图片、视频时请以原文为准。

Glen Baker 用 AI 自动化流程和 MkDocs 改造 ripgrep 文档