Markdownlint Skill
Contents
- Contents - Project Configuration - Basic Usage - Common Operations - Lint Specific Paths - Auto-Fix - Process stdin - Workflow - Standard Lint-Fix-Verify Cycle - Safe Fix with Backup - Cross-Platform Usage - Troubleshooting - No Files Matched - Too Many Issues - Configuration Not Loading - References - Installation
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 directoryAuto-Fix
markdownlint-cli2 --fix "**/*.md" # Fix all files
markdownlint-cli2 --fix README.md # Fix single fileProcess 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