不会写 Markdown，你就少了一半 AI 战斗力！Markdown 规范检查工具 rumdl

如果你想持续获取更多相关资讯，欢迎关注 x-cmd 博客。

如果你维护过大型文档项目，一定遇到过这些问题：链接失效找不到、图片路径错误、行太长影响阅读、标题层级混乱、代码块缺少语言标签。这些看似小问题，在文档规模变大后会严重拖累维护效率。

传统的 Markdown linter 如 markdownlint 速度慢、规则少、配置繁琐。rumdl 正是为解决这些痛点而生的——它把 Rust 生态中备受好评的 ruff 理念引入 Markdown 世界，用极速性能和57 条规则重新定义 Markdown 代码质量检查。

核心定位：Markdown 世界的 ruff

rumdl 把自己定位为 Markdown 领域的 ruff——这不是比喻，而是从设计理念到实现细节的全面借鉴：

• 极速性能：Rust 原生实现，检查速度比 markdownlint 快 10-100 倍
• 57 条规则：覆盖标题、列表、空白、代码块、链接、图片、样式等各个方面
• 自动修复：--fix 参数自动修复大部分问题，支持 stdin/stdout 管道
• 零依赖：单个二进制文件，无需运行时
• 多方言支持：自动识别 GFM、MkDocs、MDX、Quarto

安装方式

rumdl 支持多种安装途径，X-CMD 用户可一键安装：

# X-CMD 安装
x install rumdl

# 直接下载二进制
# 访问 https://github.com/rvben/rumdl/releases

基础使用

rumdl 提供三个核心命令：check、fmt、init。

check - 代码检查

# 检查当前目录
rumdl check .

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

# 检查并自动修复
rumdl check --fix .

# 监听模式（文件变化时自动检查）
rumdl check --watch docs/

fmt - 格式化

# 格式化当前目录
rumdl fmt .

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

格式化命令不会报告无法修复的违规——即使存在无法自动修复的问题也会返回成功，适合 CI 环境。

init - 生成配置

# 生成默认配置文件
rumdl init

这会在当前目录创建 .rumdl.toml 配置文件。

常用命令行选项

选项	说明
--config	指定配置文件路径
--disable	禁用指定规则（如 --disable MD013,MD033）
--enable	启用指定规则
--exclude	排除文件/目录（逗号分隔）
--include	只检查匹配的文件
--watch	监听模式，持续检查
--respect-gitignore	是否遵守 .gitignore（默认 true）
--no-exclude	禁用所有排除模式
--stdin-filename	指定 stdin 的文件名（用于规则检测）

stdin/stdout 管道用法

# 格式化 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

或访问在线文档：https://rumdl.dev/RULES

常用规则场景

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

# 禁用代码块语言要求（MD040）
rumdl check --disable MD040 .

# 禁用行长度检查（MD013）
rumdl check --disable MD013 README.md

GitHub Actions 集成

- 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 fmt - --quiet

" 格式化整个文件
:%!rumdl fmt - --quiet

与同类工具对比

特性	rumdl	markdownlint	mdl
性能	极速（Rust）	慢（Ruby）	慢（Ruby）
规则数	54+	60+	40+
自动修复	✅	❌	❌
依赖	零	Ruby	Ruby
配置格式	TOML	YAML/JSON	Ruby
多方言	✅ GFM/MkDocs/MDX/Quarto	有限	有限

rumdl 的核心优势在于速度和自动修复能力——这让它在大型项目和 CI/CD 环境中特别有价值。

学习建议

rumdl 的使用非常简单，建议按以下路径快速上手：

1. 先运行一次 rumdl check .，看看项目有哪些问题
2. 使用 --fix 自动修复大部分问题
3. 创建配置 rumdl init，根据项目需求调整规则
4. 加入 CI：每次 PR 自动检查，保持代码库整洁

对于 Markdown 风格要求严格的项目（如开源框架文档），建议启用所有规则，然后根据实际情况选择性禁用。