name: markdown description: > 使用 markdownlint-cli2 进行 Markdown 代码风格检查和自动修复。当 Claude 需要：(1) 检查 Markdown 文件的风格问题，(2) 修复 Markdown 格式问题，(3) 确保 Markdown 遵循最佳实践，(4) 验证 Markdown 文档，或 (5) 应用一致的 Markdown 样式时使用。

Markdown 代码风格检查

使用 markdownlint-cli2 进行自动化的 Markdown 验证和修复。

工作流程概览

1. 运行自动修复     → markdownlint-cli2 --fix <文件>
2. 检查剩余问题    → markdownlint-cli2 <文件>
3. 手动修复        → str_replace 处理结构性问题
4. 验证            → markdownlint-cli2 <文件> (应显示 0 个错误)

预期结果：自动修复解决 70-90% 的问题。剩余的 3-5 个问题需要手动修正。

基本命令

# 自动修复单个文件
markdownlint-cli2 --fix document.md

# 检查文件
markdownlint-cli2 document.md

# 多个文件
markdownlint-cli2 --fix file1.md file2.md

# 目录中所有 Markdown 文件
markdownlint-cli2 --fix "**/*.md"

# 使用自定义配置
markdownlint-cli2 --config .markdownlint.json document.md

文件路径

# 已上传的文件
markdownlint-cli2 --fix /mnt/user-data/uploads/document.md

# 工作目录
markdownlint-cli2 --fix /home/claude/document.md

# 输出给用户
cp /path/to/fixed.md /mnt/user-data/outputs/

需要手动修复的问题

自动修复无法解决以下问题 - 它们需要 Claude 的判断：

MD025 - 多个 H1 标题

原因：需要理解文档层次结构
修复：将额外的 H1 转换为适当的级别

# 主标题

# 第二个标题 → 改为：## 第二个标题

MD036 - 强调作为标题

原因：需要确定作者意图
修复：将粗体/斜体替换为正确的标题

**章节标题** → 改为：## 章节标题

MD013 - 行过长

原因：需要决定在何处断行
修复：在自然点（空格、标点符号）处换行

这是一行超过 80 个字符需要换行的非常长的文本。
↓
这是一行超过 80 个字符需要换行的
非常长的文本。

例外：URL 通常豁免

MD041 - 缺少首行标题

原因：需要结构决策
修复：在开头添加 H1 或重新结构化

执行模式

对于已上传的文件

# 1. 自动修复
markdownlint-cli2 --fix /mnt/user-data/uploads/document.md

# 2. 检查剩余问题
markdownlint-cli2 /mnt/user-data/uploads/document.md
# 输出："Summary: 3 error(s)"
# 列出具体错误，如 "MD025/single-title Multiple top-level headings"

# 3. 手动修复（示例）
str_replace "# 额外标题" → "## 额外标题"

# 4. 验证
markdownlint-cli2 /mnt/user-data/uploads/document.md
# 输出："Summary: 0 error(s)"

# 5. 输出
cp /mnt/user-data/uploads/document.md /mnt/user-data/outputs/

对于新内容

create_file /home/claude/doc.md "内容..."
markdownlint-cli2 --fix /home/claude/doc.md
markdownlint-cli2 /home/claude/doc.md
# 如有剩余问题则修复
cp /home/claude/doc.md /mnt/user-data/outputs/

配置

创建 .markdownlint.json 来自定义规则：

{
  "default": true,
  "MD013": { "line_length": 120 },
  "MD033": false
}

常见调整：

"MD013": false - 禁用行长检查
"MD013": { "line_length": 120 } - 将限制增加到 120
"MD013": { "code_blocks": false } - 排除代码块
"MD033": false - 允许 HTML
"MD041": false - 不要求首行标题

配置文件搜索顺序：

.markdownlint-cli2.jsonc
.markdownlint-cli2.yaml
.markdownlint.jsonc / .markdownlint.json
.markdownlint.yaml / .markdownlint.yml

向用户报告

提供清晰的修复摘要：

✅ Markdown 代码风格检查完成！

初始：18 个错误
自动修复后：4 个错误
手动修复：
  • MD025：将 2 个 H1 标题转换为 H2
  • MD036：将粗体替换为正确标题
  • MD013：换行长行

最终：0 个错误

错误计数解释

自动修复前：

0-5：小问题
6-15：中等问题
16+：严重问题

自动修复后：

0-2：优秀
3-5：典型
6+：检查是否需要配置

常见修复模式

# 多个 H1 - 首先分析结构
# 如果是章节：转换为 H2
str_replace "# 介绍" → "## 介绍"

# 如果是子章节：转换为 H3
str_replace "# 详情" → "### 详情"

# 强调作为标题 - 确定适当级别
str_replace "**重要**" → "## 重要"
str_replace "_注意_" → "### 注意"

# 长行 - 在自然点处断行
# 连词后：和、但、或
# 标点符号后：， 。 ；
# 保持 URL 在单行

故障排除

自动修复不工作：

# 检查文件是否存在
view /path/to/file.md

# 验证权限
ls -l /path/to/file.md

# 使用绝对路径
markdownlint-cli2 --fix /full/path/to/file.md

自动修复后错误太多：

# 创建宽松配置
echo '{"MD013": false, "MD041": false}' > .markdownlint.json
markdownlint-cli2 --config .markdownlint.json --fix file.md

特定规则导致问题：

在配置中禁用："MD013": false
或调整参数："MD013": { "line_length": 120 }

何时不进行代码风格检查

在以下情况下跳过代码风格检查：

代码示例故意违反规则
需要嵌入 HTML/JSX（禁用 MD033）
具有不同约定的生成文档
更改会破坏引用的遗留文档

使用自定义配置禁用有问题的规则。

快速规则参考

Claude 将遇到的最常见规则：

MD001 - 标题逐级递增
MD004 - 一致的列表标记
MD009 - 无尾随空格
MD010 - 无硬制表符
MD012 - 无多个空行
MD013 - 行长（默认：80）
MD018 - 标题中 # 后有空格
MD022 - 标题周围空行
MD025 - 仅单个 H1
MD031 - 代码块周围空行
MD032 - 列表周围空行
MD034 - 尖括号中的裸 URL
MD036 - 无强调作为标题
MD040 - 代码块的语言

完整规则文档：https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md