Markdown linter 往往是在项目变大之后才被认真对待的工具。早期只有几篇 README 和设计文档时，人工 review 足够发现标题层级、空行、列表缩进和行宽问题；但当仓库里有上百甚至上千个 Markdown 文件，lint 就会进入 CI、pre-commit 和文档发布流程。这个阶段，速度和可配置性会直接影响开发体验。

今天推荐的 akiomik/mado 是一个用 Rust 写的 Markdown linter。它的目标很明确：在兼容 CommonMark 和 GitHub Flavored Markdown 的前提下，提供 markdownlint 风格的规则检查，并把运行速度压低到足够适合大文档仓库。

发布时 GitHub 页面显示项目约 377 stars、10 forks，主要语言是 Rust，许可为 Apache-2.0。仓库创建于 2024-12-16，最近 push 时间为 2026-06-15。release 页面显示最新版本为 v0.3.0，GitHub 发布于 2025-04-11。

项目概览

属性详情
仓库akiomik/mado
定位Rust Markdown linter
Stars约 377
Forks10
主要语言Rust
许可Apache-2.0
最新版本v0.3.0

先解决“跑得够快”的问题

Mado README 里最醒目的卖点是性能。项目给出的 benchmark 使用 GitLab 文档作为数据集，大约检查 1,500 个 Markdown 文件，并用 hyperfine 对比 mado、Ruby 版 markdownlint、Node 生态的 markdownlint-cli 和 markdownlint-cli2。

这个结果需要按“项目自测 benchmark”来看，而不是当成所有仓库都能复现的绝对结论。但它指出了一个真实痛点：Markdown lint 不应该慢到让人绕开它。文档仓库越大，lint 越容易被放进 CI、pre-push hook 或本地保存前检查；如果每次检查都要等待很久，团队最后往往会降低运行频率，或者只在发布前集中修格式。

Rust 实现的价值就在这里。Mado 把 Markdown parsing、规则遍历和文件扫描做成一个低延迟 CLI，让它更适合频繁运行，而不是只作为偶尔执行的文档卫生检查。

接近 markdownlint 的规则模型

Mado 支持多数 markdownlint 规则。README 的规则表把每条规则标成 stable、unstable、unsupported option 或 not supported。常见的标题层级、尾随空格、重复空行、行宽、列表缩进、代码块语言、文件末尾换行等规则都在覆盖范围内。

这点很重要，因为 Markdown lint 的难点不是“能不能检查某一种格式”，而是团队已有规则如何迁移。很多项目已经熟悉 MD001、MD013、MD024 这类 markdownlint 规则编号。如果新工具完全重造一套命名和配置模型，迁移成本会明显变高。

Mado 没有宣称 100% 覆盖所有 markdownlint 行为。它把当前支持程度列出来，反而更适合谨慎采用：你可以先用在新仓库，或者在旧仓库里把关键规则逐步对齐，再决定是否替换原有 lint 工具。

配置和安装方式比较完整

Mado 的基本用法很直接：

mado check .
mado check path/to/*.md

配置文件可以是当前目录下的 mado.toml 或 .mado.toml，也可以放在用户级配置目录。README 还链接了示例配置和 JSON Schema，这对编辑器补全、配置审查和仓库模板都很有用。

安装方式也覆盖了几个常见场景：

  1. macOS / Linux 可以用 Homebrew 或 Nix。
  2. Arch Linux 可以通过 pacman -S mado。
  3. Windows 可以通过 Scoop 或 WinGet manifest。
  4. 不想接入包管理器时，可以从 release 页面下载预构建二进制。

对一个 CLI 工具来说，这些渠道比“只给 cargo install”更实际。文档团队、平台工程团队和 CI 镜像不一定都愿意现场编译 Rust 项目，预构建包和常见包管理器能降低接入摩擦。

GitHub Actions 支持适合文档仓库

Mado 也提供 GitHub Actions 用法：

- uses: akiomik/mado@v0.3.0

如果需要传入自定义参数，也可以用 args 指定配置和检查路径。比如只检查某个文档目录，或者显式传入 mado.toml。

这个设计让它不只是一个本地 CLI。很多文档质量问题本质上应该在 PR 阶段发现：标题跳级、列表缩进不一致、代码块缺少语言、行宽过长、文件末尾缺少换行。把这些规则放进 CI 后，reviewer 可以少关注机械格式，把注意力留给内容准确性。

v0.3.0 带来了 tags 和 shell completion

最新 release v0.3.0 的更新重点包括 tags 和 shell completion，同时升级了 comrak 等依赖。它还包含一个 breaking change：comrak 从 0.36.0 升到 0.38.0。

对用户来说，shell completion 是很实用的 CLI 细节；对维护者来说，持续跟进 Markdown parser 依赖也很关键。Markdown linter 的正确性很大程度依赖 parser 对 CommonMark 和 GFM 的处理，如果底层 parser 长期不更新，规则层再完整也会逐渐偏离真实文档生态。

Mado 目前仍是相对年轻的项目。它的 release 节奏和规则覆盖还需要继续观察，但从 README、安装渠道、GitHub Actions、schema、benchmark 和 fuzz testing 这些细节看，作者不是只写了一个一次性命令，而是在朝可维护工具链推进。

适合什么场景

Mado 最适合这几类项目：

  1. Markdown 文件很多，现有 lint 在 CI 或本地运行偏慢。
  2. 想保留 markdownlint 风格规则，但希望尝试更快的实现。
  3. 文档仓库需要跨 macOS、Linux、Windows 安装同一个 CLI。
  4. 希望把 Markdown lint 明确放进 GitHub Actions，而不是只靠人工 review。
  5. 对 Rust 工具链友好，愿意接受一个仍在成长中的 linter。

它不一定适合所有团队。如果项目高度依赖 markdownlint 的某些特殊选项，或者已经有复杂的自定义规则生态，直接替换可能并不划算。更稳妥的方式是先在独立文档目录或新仓库里试跑，比较规则差异和误报，再决定迁移范围。

小结

akiomik/mado 是一个定位清楚的 Markdown lint 工具：用 Rust 提供更快的检查速度，沿用 markdownlint 熟悉的规则模型，并补齐配置、安装、GitHub Actions 和 schema 等工程化细节。

如果你的仓库里 Markdown 已经多到 lint 成为等待成本，Mado 值得加入候选列表。它不是要重新定义文档规范，而是让已有的 Markdown 规范更容易在本地和 CI 里高频执行。