Mado：基于 Pull-Parser 架构的高性能 Markdown Linter 设计与实现

在文档工程化日益重要的今天，Markdown linter 已成为 CI 流水线中的标准组件。然而，传统基于 Ruby 或 Node.js 的实现（如 markdownlint）在处理大型文档库时往往成为性能瓶颈。mado 作为一款用 Rust 编写的 Markdown linter，通过重新思考解析器架构，在 M1 Max 设备上处理 1500 个 Markdown 文件仅需 0.129 秒，相较 markdownlint-cli 的 6.381 秒实现了约 60 倍的性能提升。

Pull-Parser 架构：事件流替代 AST

mado 的核心性能优势源于其采用的 pull-parser 设计模式。与构建完整抽象语法树（AST）的传统解析器不同，mado 基于 pulldown-cmark 实现了一个事件流驱动的解析引擎。这种架构将 Markdown 文档解析为一系列事件（如 Start、End、Text、Code），规则引擎在事件流经过时实时进行检查，无需一次性将整个文档加载到内存中。

这种设计的工程价值体现在三个层面：首先是内存效率，事件流处理避免了大型 AST 的内存分配，对于包含大量嵌套结构的文档尤为明显；其次是缓存友好性，顺序访问模式充分利用了 CPU 缓存行，减少了指针跳转带来的缓存未命中；最后是延迟计算，规则检查可以在解析过程中并行进行，无需等待完整解析结束。正如 pulldown-cmark 的设计哲学所示，这种 "按需拉取" 的模式在保持 CommonMark 规范兼容性的同时，实现了接近线性扫描的性能特征。

规则引擎：状态机驱动的轻量检查

mado 的规则引擎采用了与解析器协同的状态机设计。当解析器产生事件时，规则引擎维护一个轻量级的上下文状态栈，用于跟踪当前所处的文档结构（如列表层级、代码块边界、标题层级等）。这种状态机方法使得规则检查可以在 O (1) 空间复杂度内完成，避免了递归遍历 AST 的开销。

目前 mado 支持 40 余条 markdownlint 兼容规则，涵盖标题层级一致性（MD001/MD002）、列表缩进（MD007）、代码块语言标识（MD040）等常见检查项。值得注意的是，部分规则标记为 "不稳定" 状态，这反映了事件流架构在处理某些需要前瞻或回溯的复杂规则时的固有挑战。例如，检测重复的标题文本（MD024）需要在多个事件之间维护一个跨节点的状态映射，这在纯流式处理中需要额外的缓冲策略。

工程实践：从配置到 CI 集成

mado 的配置采用 TOML 格式，支持项目级（mado.toml 或 .mado.toml）和全局级（~/.config/mado/mado.toml）两种配置方式。对于团队项目，推荐在仓库根目录放置 .mado.toml 并纳入版本控制，确保所有成员使用一致的规则集。

在 CI 环境中，mado 提供了官方 GitHub Action，基础用法仅需一行配置：

- uses: akiomik/mado@v0.3.0

对于需要自定义规则集的项目，可以通过 args 参数指定配置文件路径：

- uses: akiomik/mado@v0.3.0
  with:
    args: '--config path/to/mado.toml check docs/**/*.md'

性能监控方面，mado 内置了基于 flamegraph 的 profiling 支持。通过 just flamegraph 命令可以生成火焰图，帮助识别规则检查中的热点。对于追求极致性能的场景，建议使用 hyperfine 进行基准测试，对比不同配置下的处理延迟。

局限与权衡

尽管 pull-parser 架构带来了显著的性能收益，但这种设计也存在固有的权衡。事件流模型在处理需要跨节点关联的语义检查时会增加实现复杂度，例如检测文档中未使用的引用链接（MD052）需要在整个文档范围内维护引用定义与使用的映射关系。此外，mado 目前主要聚焦于 CommonMark 和 GFM 规范，对于其他 Markdown 方言（如 MultiMarkdown、Markua）的支持尚不完善。

另一个值得注意的点是错误定位的精确性。由于事件流处理的是字符范围而非节点对象，错误消息的生成需要依赖 into_offset_iter() 提供的源文本偏移信息。在极端情况下，如果解析器与规则引擎之间的偏移映射出现偏差，可能导致错误定位不够精确。

总结

mado 代表了 Markdown 工具链向高性能原生编译方向演进的一个典型案例。通过采用 pull-parser 架构和事件流驱动的规则引擎，它在保持规范兼容性的同时，将 lint 任务的执行时间从秒级降低到毫秒级。对于拥有大量 Markdown 文档的仓库（如文档站点、开源项目 wiki），这种性能提升可以显著缩短 CI 反馈周期。

在工程实践中，建议将 mado 作为预提交钩子（pre-commit hook）和 CI 检查的双重防线配置，结合 mado.toml 的细粒度规则控制，在代码入库前捕获格式问题。随着项目成熟，mado 有望成为 Rust 生态中 Markdown 工具链的标准组件之一。

资料来源

• mado GitHub 仓库：https://github.com/akiomik/mado
• pulldown-cmark 架构文档：https://github.com/pulldown-cmark/pulldown-cmark

developer-tools