Rust 实现的 Markdown 检查工具 rumdl：57 条规则一键自动修复

如果你维护过包含大量 Markdown 文件的文档项目、博客仓库或知识库，想必对以下问题不会陌生：某个链接突然失效却难以定位，图片路径因复制粘贴而错误，过长的行在编辑器和网页上严重影响阅读体验，标题层级混乱导致结构不清，或者代码块缺少必要的语言标签导致语法高亮失效。这些看似琐碎的格式问题，一旦文档规模增长，就会严重拖慢协作和维护效率。

传统的 Markdown 规范检查工具，例如 markdownlint，虽然功能全面，但检查速度较慢、规则配置相对繁琐。而 rumdl 正是为应对这些痛点而诞生的。它将 Rust 生态中广受赞誉的 ruff 工具的理念引入 Markdown 领域，致力于用极致性能和丰富的内置规则重新定义 Markdown 文档的代码质量检查。

核心定位：Markdown 领域的“Ruff”

rumdl 将自己明确为 Markdown 世界的 ruff——这并非简单的比喻，而是从底层设计哲学到实现细节的全面借鉴：

• 极速性能：采用 Rust 原生实现，官方宣称其检查速度比基于 Ruby 的 markdownlint 快 10 到 100 倍。
• 57 条内置规则：覆盖了标题、列表、空白字符、代码块、链接、图片、样式等 Markdown 的各个方面，开箱即用。
• 自动修复：通过 --fix 参数，可以一键自动修复大部分可纠正的问题，并完美支持 stdin/stdout 管道操作。
• 零运行时依赖：提供单个可执行二进制文件，下载即用，无需安装额外的运行时环境。
• 多方言智能支持：能够自动识别并处理 GitHub Flavored Markdown (GFM)、MkDocs、MDX 以及 Quarto 等多种 Markdown 方言和扩展语法。

安装方式

rumdl 支持多种安装途径。对于 X-CMD 用户，安装尤为便捷：

x install rumdl

你也可以通过 Cargo（Rust 包管理器）直接安装：

cargo install rumdl

或者从 GitHub Releases 页面下载对应平台预编译的二进制文件。

基础使用

rumdl 提供了三个核心子命令：check（检查）、fmt（格式化）和 init（初始化配置）。

check - 代码质量检查

这是最常用的命令，用于扫描并报告文档中的格式问题。

# 检查当前目录下的所有 Markdown 文件
rumdl check .

# 检查指定的单个文件
rumdl check README.md

# 检查并尝试自动修复所有可修复的问题
rumdl check --fix .

# 启用监听模式，文件变化时自动执行检查
rumdl check --watch docs/

fmt - 格式化文档

此命令专注于格式化，它会直接修改文件，但不会报告无法自动修复的违规项。即使存在无法修复的问题，命令也会返回成功状态码，这使其非常适合集成到 CI/CD 流程中。

# 格式化当前目录下的所有 Markdown 文件
rumdl fmt .

# 格式化单个文件
rumdl fmt README.md

init - 生成配置文件

如果你需要自定义规则，可以使用此命令生成一个配置文件模板。

# 在当前目录生成默认的 .rumdl.toml 配置文件
rumdl init

常用命令行选项

rumdl 提供了丰富的命令行选项以满足不同场景的需求：

选项	说明
--config	指定自定义配置文件的路径。
--disable	禁用指定的规则，例如 --disable MD013,MD033。
--enable	启用指定的规则（覆盖配置）。
--exclude	排除指定的文件或目录（逗号分隔）。
--include	只检查匹配指定模式的文件。
--watch	启用监听模式。
--respect-gitignore	是否遵守 .gitignore 文件（默认为 true）。
--no-exclude	禁用所有排除模式，检查所有文件。
--stdin-filename	为从 stdin 读取的内容指定一个“文件名”，这会影响某些基于文件扩展名或路径的规则。

stdin/stdout 管道用法

rumdl 完美支持管道操作，便于集成到脚本或其他工具链中。

# 格式化从 stdin 输入的内容
echo "# Title " | rumdl fmt -
cat README.md | rumdl fmt - > README_formatted.md

# 检查 stdin 的内容
cat README.md | rumdl check - --stdin-filename README.md

配置文件说明

rumdl 使用 TOML 格式的配置文件。它会按以下顺序查找配置：

1. .rumdl.toml
2. rumdl.toml
3. .config/rumdl.toml

你也可以将配置集成到项目的 pyproject.toml 文件中：

[tool.rumdl]
# 启用/禁用特定规则
enable = ["MD001", "MD003"]
disable = ["MD013", "MD033"]

# 文件过滤
include = ["docs/*.md", "README.md"]
exclude = ["node_modules", "dist", "CHANGELOG.md"]

# 指定 Markdown 方言
markdown = "gfm"  # 可选值：gfm, mdx, mkdocs, quarto

# 针对特定规则的详细配置
[tool.rumdl.rules]
MD013 = { line_length = 100 }
MD009 = { br_spaces = 2 }

查看当前生效的配置

rumdl config              # 查看所有生效的配置
rumdl config --defaults   # 只显示默认值
rumdl config --no-defaults # 只显示非默认（自定义）值

规则集一览

rumdl 实现了 54 条核心规则（官方文档有时显示为 57 条），并进行了清晰的分类：

类别	规则示例	功能说明
Headings（标题）	MD001-MD003	检查标题层级是否连贯、标题符号是否一致等。
Lists（列表）	MD004-MD007	检查列表标记样式（如-，*，+）是否统一、缩进是否正确。
Whitespace（空白）	MD009-MD012	检查行尾多余空格、是否使用了硬标签等。
Code（代码）	MD040, MD046-MD048	检查代码块是否指定了语言标签、代码块格式是否正确。
Links（链接）	MD034, MD039-MD042	检查链接格式、引用式链接是否有效等。
Images（图片）	MD045, MD052-MD053	检查图片是否包含 alt 文本、图片引用是否有效。
Style（样式）	MD031-MD036	检查块引用、水平线等样式元素的格式。

查看完整的规则列表及其详细说明：

rumdl rule

你也可以访问其在线文档进行查阅。

常用规则配置场景

在实际项目中，你可能需要根据团队规范调整某些规则。例如：

# 禁用表格列宽限制检查（规则 MD.table_columns）
rumdl check --disable MD.table_columns docs/

# 禁用代码块必须指定语言的要求（规则 MD040）
rumdl check --disable MD040 .

# 禁用行长度限制检查（规则 MD013），这在某些包含长链接或表格的文档中很有用
rumdl check --disable MD013 README.md

集成到 GitHub Actions

你可以在项目的 CI 流水线中轻松集成 rumdl，确保每次提交都符合代码规范。

使用社区维护的 Action：

- name: Lint Markdown
  uses: rvben/rumdl@v1
  with:
    args: 'check .'

或者手动安装后执行：

- name: Install rumdl
  run: cargo install rumdl

- name: Lint Markdown
  run: rumdl check .

编辑器集成

VS Code

在 VS Code 扩展商店中搜索 “rumdl” 并安装官方或社区维护的扩展，即可在编辑器中获得实时检查和快速修复功能。

Vim/Neovim

你可以通过配置，使用 rumdl 来格式化选中的文本或整个文件。

" 格式化选中的视觉模式区域
:'<,'>!rumdl fmt - --quiet

" 格式化整个缓冲区
:%!rumdl fmt - --quiet

与同类工具对比

为了更好地理解 rumdl 的定位，我们可以将其与 markdownlint 和 mdl 进行简单对比：

特性	rumdl	markdownlint	mdl
性能	极速 (Rust 原生)	较慢 (Ruby)	较慢 (Ruby)
规则数量	54+	60+	40+
自动修复	✅ 支持	❌ 不支持	❌ 不支持
运行时依赖	零 (单二进制文件)	需要 Ruby	需要 Ruby
配置格式	TOML	YAML/JSON	Ruby DSL
多方言支持	✅ (GFM/MkDocs/MDX/Quarto)	有限	有限

rumdl 的核心优势在于其卓越的速度和强大的自动修复能力，这使得它在需要处理大量文档的大型项目，以及追求快速反馈的 CI/CD 环境中具有显著价值。

上手建议

rumdl 的学习曲线非常平缓。建议按照以下路径快速将其集成到你的工作流中：

1. 初次诊断：在项目根目录运行 rumdl check .，全面了解现有文档的所有格式问题。
2. 一键修复：使用 rumdl check --fix . 命令，让工具自动修复所有它能处理的问题。
3. 定制规则：运行 rumdl init 创建配置文件，根据团队或项目的具体风格指南，启用、禁用或调整特定规则。
4. 持续守护：将 rumdl check 步骤添加到你的 CI 配置（如 GitHub Actions）中，确保每次代码提交或合并请求都能自动进行文档规范检查，保持仓库的长期整洁。

对于像开源框架文档这类对 Markdown 风格有严格要求的项目，一个有效的策略是：在配置中启用所有规则，然后根据实际遇到的误报或项目特殊性，在配置文件中逐一、明确地禁用那些不适用条款。

项目主页与源码：

• 项目源码：https://github.com/rvben/rumdl
• 官方文档：https://rumdl.dev

你是否已经在项目中尝试过类似的文档质量工具？对于使用 Rust 重写传统工具以提升性能的“现代工具链”趋势，有什么看法？欢迎在云栈社区分享你的实践经验或探讨更多技术文档的最佳实践。