markdownlint
当用户需要使用 markdownlint-cli2 命令行工具格式化、清理、检查或验证 Markdown 文件时使用此技能。用于涉及 Markdown 文件质量检查、自动格式修复、强制执行 Markdown 样式规则或识别 Markdown 语法问题的任务。
📖 中文导读:当用户需要使用 markdownlint-cli2 命令行工具格式化、清理、检查或验证 Markdown 文件时使用此技能。用于涉及 Markdown 文件质量检查、自动格式修复、强制执行 Markdown 样式规则或识别 Markdown 语法问题的任务。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: markdownlint
description: This skill should be used when users need to format, clean, lint, or validate Markdown files using the markdownlint-cli2 command-line tool. Use this skill for tasks involving Markdown (including Quarto Markdown .qmd) file quality checks, automatic formatting fixes, enforcing Markdown style rules, or identifying Markdown syntax issues.
Markdownlint Skill
Contents
Project Configuration
IMPORTANT: This project uses .markdownlint.yaml. Always follow these rules:
| Rule | Setting | Notes |
|---|---|---|
| MD040 | Enabled | Always specify language for code fences |
| MD007 | 2 spaces | List indentation |
| MD024 | Siblings only | Duplicate headings allowed under different parents |
| MD013 | Disabled | No line length restrictions |
| MD033 | Disabled | Inline HTML allowed |
| MD041 | Disabled | Files don't need to start with H1 |
| MD038 | Disabled | Spaces in code spans allowed |
| MD036 | Disabled | Emphasis as heading allowed |
Basic Usage
# Lint files
markdownlint-cli2 "**/*.md"
markdownlint-cli2 README.md
# Auto-fix issues
markdownlint-cli2 --fix "**/*.md"
# Exclude directories
markdownlint-cli2 "**/*.md" "#node_modules" "#vendor"
Common Operations
Lint Specific Paths
markdownlint-cli2 README.md # Single file
markdownlint-cli2 "docs/**/*.md" # Directory
markdownlint-cli2 "*.md" "docs/**/*.md" # Multiple patterns
markdownlint-cli2 . # Current directory
Auto-Fix
markdownlint-cli2 --fix "**/*.md" # Fix all files
markdownlint-cli2 --fix README.md # Fix single file
Process stdin
cat README.md | markdownlint-cli2 -
Workflow
Standard Lint-Fix-Verify Cycle
- Run lint check:
markdownlint-cli2 "**/*.md" - Review reported issues
- Apply auto-fix:
markdownlint-cli2 --fix "**/*.md" - Re-run lint to verify:
markdownlint-cli2 "**/*.md" - Review changes:
git diff - Commit when satisfied
Safe Fix with Backup
- Stage current state:
git add . - Create backup commit:
git commit -m "Backup before markdownlint fix" - Apply fixes:
markdownlint-cli2 --fix "**/*.md" - Review changes:
git diff - Commit fixes or reset:
git add . && git commit -m "Apply markdownlint fixes"
Cross-Platform Usage
For maximum compatibility:
- Quote glob patterns:
markdownlint-cli2 "**/*.md" - Use
#for negation:markdownlint-cli2 "**/*.md" "#vendor"(not!) - Use forward slashes:
docs/**/*.md(works on all platforms) - Stop option processing:
markdownlint-cli2 -- "special-file.md"
Troubleshooting
No Files Matched
- Verify glob patterns are quoted
- Check file extensions (
.mdvs.markdown) - Ensure negated patterns don't exclude everything
Too Many Issues
- Start with auto-fix:
markdownlint-cli2 --fix "**/*.md" - Disable problematic rules temporarily
- Address remaining issues incrementally
Configuration Not Loading
- Verify configuration file name matches expected patterns
- Validate JSON/YAML syntax
- Use
--configto explicitly specify the file
References
- Rules Reference - Complete rule descriptions
- Configuration Examples - Config templates and patterns
- Official Documentation
- All Rules
Installation
npm install -g markdownlint-cli2 # npm
brew install markdownlint-cli2 # Homebrew
markdownlint-cli2 --help # Verify installation