SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsmarkdown-lint

markdown-lint

Coding & development

View repository

Updated 10-15 16:43

About this skill

Markdown Lint

Configure markdown format checking (markdownlint + horizontal rule prohibition) and a pre-commit hook for the repository.

Prerequisites

Tool Type Required Install
Node.js cli Yes brew install node or nodejs.org
markdownlint-cli2 cli Yes npx markdownlint-cli2 (no install needed)
pre-commit cli No uv tool install pre-commit --with pre-commit-uv or pipx install pre-commit or brew install pre-commit

Do NOT proactively verify these tools on skill load. If a command fails due to a missing tool, directly guide the user through installation and configuration step by step.

When to Use

  • New repository initialization: add markdown format standards to a repository for the first time
  • Check/fix: run format checks or batch-fix existing files
  • Migration: copy the format standards to another repository

Not applicable:

  • Single-file check: run directly npx markdownlint-cli2 file.md, no need to go through the setup process
  • Article content review: use the writing-assistant skill (step 6 of that skill references this skill; requires installing personal-knowledge plugin）

Setup process

1. Check repository status

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

2. Create configuration file

.markdownlint.json：

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

Explanation of disabled rules:

Rule Reason
MD013 CJK text and tables are not suitable for line length limits
MD033 Allow <br>, <small> and other inline HTML
MD035 Horizontal rules are completely prohibited, checked by a separate script
MD036 Allow bold as visual headings
MD041 YAML frontmatter causes the first line to be non-heading
MD060 Table pipe spacing style is overly strict

Append as needed to disable(add as appropriate based on repository content):

Rule Scenario Reason
MD025 Repository contains imported/vendor documentation Protocol documentation often has multiple H1s
MD045 Repository contains imported/vendor documentation Vendor documentation images lack alt text
MD051 CJK anchor links #_中文标题 fragments in the format are not recognized
MD056 Complex reference tables Tables with merged rows/variable-length columns trigger false positives

.pre-commit-config.yaml：

repos:
  - repo: https://github.com/DavidAnson/markdownlint-cli2
    rev: v0.21.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]

Must run after creation pre-commit autoupdate, the rev above may be outdated.

scripts/check-horizontal-rules.sh：

Copy from scripts/check-horizontal-rules.sh , then chmod +x。

Windows users：.sh The script needs to be run in Git Bash or WSL.

.gitignore(if not present):

node_modules/
.mypy_cache/
__pycache__/

3. Remove existing --- separator lines

Keep the ---of YAML frontmatter, delete all other horizontal rules:

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

# 提取违规文件列表（仅匹配 .md: 格式的行，避免捕获错误消息）
files=$(bash scripts/check-horizontal-rules.sh \
  $(find . -name '*.md' -not -path './node_modules/*') 2>&1 \
  | grep -E '\.md:[0-9]+:' | grep -oE '^[^:]+' | sort -u)

# 批量移除（保留 frontmatter）
for file in $files; 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"
  echo "Fixed: $file"
done

Note: grep must use \.md:[0-9]+: filtering, otherwise the "Error: ..." error message at the end of the script will be treated as a filename.

4. Format all files

# 单仓库
npx markdownlint-cli2 --fix "**/*.md"
npx markdownlint-cli2 "**/*.md"

# monorepo（排除子仓库和依赖目录）
npx markdownlint-cli2 --fix "**/*.md" "#repos" "#node_modules"
npx markdownlint-cli2 "**/*.md" "#repos" "#node_modules"

4a. Handle errors that cannot be auto-fixed

--fix Common errors that cannot be fixed:

  • MD040(code block missing language): add to ``` a language identifier (python、bash、yaml、text etc.)
  • MD025/MD045/MD051/MD056: if a large number appear in vendor documentation, disable the corresponding rule in .markdownlint.json .

Analyze the error distribution first before deciding on a strategy:

# 按规则统计
npx markdownlint-cli2 "**/*.md" "#repos" "#node_modules" 2>&1 \
  | grep -oE 'MD[0-9]+' | sort | uniq -c | sort -rn

# 按文件统计
npx markdownlint-cli2 "**/*.md" "#repos" "#node_modules" 2>&1 \
  | grep -oE '^[^:]+' | sort | uniq -c | sort -rn | head -10

5. Install hook

pre-commit install

6. Verify

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

Check/fix (repositories with existing configuration)

npx markdownlint-cli2 "**/*.md" "#repos" "#node_modules"            # 检查
npx markdownlint-cli2 --fix "**/*.md" "#repos" "#node_modules"      # 自动修复
bash scripts/check-horizontal-rules.sh $(find . -name '*.md' -not -path './repos/*' -not -path './node_modules/*')

For single-repository projects, remove "#repos" and that's it.

Common issues

Issue Cause Fix
pre-commit: command not found Not installed uv tool install pre-commit --with pre-commit-uv(recommended) or pipx install pre-commit / brew install pre-commit
markdownlint has many MD060 errors Table pipe spacing .markdownlint.json in "MD060": false
many MD056 errors vendor documentation complex tables .markdownlint.json in "MD056": false
many MD051 errors CJK anchor links .markdownlint.json in "MD051": false
.sh script cannot execute on Windows Windows does not natively support Bash Use Git Bash or WSL
frontmatter --- was accidentally deleted awk script issue Confirm that line 1 of the file is --- and is immediately followed by YAML content
Bulk deletion of HR produces junk .tmp files grep captured script error messages as filenames Use grep -E '\.md:[0-9]+:' to filter, matching only file path lines
--fix did not fix all issues Some rules cannot be auto-fixed Manually fix (usually MD040 missing code block language, add ```text , etc.)