name: markdown-lint
description: Use when setting up or running markdown formatting and linting in a repository, or when encountering markdownlint errors (MD013, MD040, MD060) or horizontal rule violations. Triggers on「格式化 markdown」「设置 markdown lint」「markdown 检查」「设置 pre-commit」「检查 md 格式」「markdownlint 报错」

Markdown Lint

为仓库配置 markdown 格式检查（markdownlint + 水平线禁止）和 pre-commit hook。

When to Use

• 新仓库初始化：第一次为仓库添加 markdown 格式标准
• 检查/修复：运行格式检查或批量修复现有文件
• 迁移：将格式标准复制到另一个仓库

不适用：

• 单文件检查：直接运行 npx markdownlint-cli2 file.md，不需要走 setup 流程
• 文章内容审校：使用 writing-proofreading skill（步骤 6 会引用本 skill）

前置条件

# 安装 pre-commit（git hooks 需要持久安装，选择一种方式）
uv tool install pre-commit --with pre-commit-uv  # 推荐，跨平台最快
pipx install pre-commit                           # 备选，跨平台
brew install pre-commit                           # macOS/Linux

# 一次性运行检查（不需要安装）
uvx pre-commit run --all-files

node --version             # 需要 Node.js（markdownlint 依赖）

Setup 流程

1. 检查仓库状态

# 已有配置？跳到「检查/修复」
ls .markdownlint.json .pre-commit-config.yaml 2>/dev/null

2. 创建配置文件

.markdownlint.json：

{
  "default": true,
  "MD013": false,
  "MD024": { "siblings_only": true },
  "MD033": false,
  "MD035": false,
  "MD036": false,
  "MD041": false,
  "MD060": false
}

关闭规则说明：

.pre-commit-config.yaml：

repos:
  - repo: https://github.com/DavidAnson/markdownlint-cli2
    rev: v0.20.0  # 运行 pre-commit autoupdate 获取最新
    hooks:
      - id: markdownlint-cli2
  - repo: local
    hooks:
      - id: no-horizontal-rules
        name: no horizontal rules outside frontmatter
        entry: scripts/check-horizontal-rules.sh
        language: script
        types: [markdown]

创建后必须运行 pre-commit autoupdate，上面的 rev 可能已过时。

scripts/check-horizontal-rules.sh：

从 scripts/check-horizontal-rules.sh 复制，然后 chmod +x。

Windows 用户：.sh 脚本需要在 Git Bash 或 WSL 中运行。

.gitignore（如果没有）：

node_modules/
.mypy_cache/
__pycache__/

3. 移除现有 --- 分隔线

保留 YAML frontmatter 的 ---，删除其余所有水平线：

# 找出违规文件
bash scripts/check-horizontal-rules.sh $(find . -name '*.md' -not -path './node_modules/*')

# 批量移除（保留 frontmatter）
for file in $(bash scripts/check-horizontal-rules.sh \
  $(find . -name '*.md' -not -path './node_modules/*') 2>&1 \
  | grep -oE '^[^:]+' | sort -u); do
  awk '
    NR == 1 && /^---[[:space:]]*$/ { print; fm = 1; next }
    fm && /^---[[:space:]]*$/ { print; fm = 0; next }
    !fm && /^[[:space:]]*[-*_][[:space:]]*[-*_][[:space:]]*[-*_][-*_ ]*$/ { next }
    { print }
  ' "$file" > "$file.tmp" && mv "$file.tmp" "$file"
done

4. 格式化全部文件

npx markdownlint-cli2 --fix "**/*.md"
npx markdownlint-cli2 "**/*.md"        # 确认零错误

5. 安装 hook

pre-commit install

6. 验证

# 三项检查全部通过
npx markdownlint-cli2 "**/*.md"
bash scripts/check-horizontal-rules.sh $(find . -name '*.md' -not -path './node_modules/*')
# 测试 hook: 故意加 --- 到某 md 文件，git add + commit，应被拦截

检查/修复（已有配置的仓库）

npx markdownlint-cli2 "**/*.md"            # 检查
npx markdownlint-cli2 --fix "**/*.md"      # 自动修复
bash scripts/check-horizontal-rules.sh **/*.md  # HR 检查

常见问题