Markdown Lint
Automated markdown validation and fixing using markdownlint-cli2.
Workflow Overview
1. Run auto-fix → markdownlint-cli2 --fix <file>
2. Check remaining → markdownlint-cli2 <file>
3. Fix manually → str_replace for structural issues
4. Verify → markdownlint-cli2 <file> (should show 0 errors)
Expected results: Auto-fix resolves 70-90% of issues. Remaining 3-5
issues require manual correction.
Basic Commands
# Auto-fix single file
markdownlint-cli2 --fix document.md
# Check file
markdownlint-cli2 document.md
# Multiple files
markdownlint-cli2 --fix file1.md file2.md
# All markdown in directory
markdownlint-cli2 --fix "**/*.md"
# With custom config
markdownlint-cli2 --config .markdownlint.json document.md
File Paths
# Uploaded files
markdownlint-cli2 --fix /mnt/user-data/uploads/document.md
# Working directory
markdownlint-cli2 --fix /home/claude/document.md
# Output to user
cp /path/to/fixed.md /mnt/user-data/outputs/
Manual Fixes Required
Auto-fix cannot resolve these issues - they need Claude's judgment:
MD025 - Multiple H1 Headers
Why: Requires understanding document hierarchy
Fix: Convert extra H1s to appropriate level
# Main Title
# Second Title → Change to: ## Second Title
MD036 - Emphasis as Header
Why: Requires determining author intent
Fix: Replace bold/italic with proper header
**Section Title** → Change to: ## Section Title
MD013 - Line Too Long
Why: Requires deciding where to break content
Fix: Wrap at natural points (spaces, punctuation)
This is a very long line exceeding 80 characters that needs wrapping.
↓
This is a very long line exceeding 80 characters that needs
wrapping.
Exception: URLs typically exempt
MD041 - Missing First Line Header
Why: Requires structural decision
Fix: Add H1 at start or restructure
Execution Pattern
For Uploaded Files
# 1. Auto-fix
markdownlint-cli2 --fix /mnt/user-data/uploads/document.md
# 2. Check remaining
markdownlint-cli2 /mnt/user-data/uploads/document.md
# Output: "Summary: 3 error(s)"
# Lists specific errors like "MD025/single-title Multiple top-level headings"
# 3. Manual fixes (example)
str_replace "# Extra Title" → "## Extra Title"
# 4. Verify
markdownlint-cli2 /mnt/user-data/uploads/document.md
# Output: "Summary: 0 error(s)"
# 5. Output
cp /mnt/user-data/uploads/document.md /mnt/user-data/outputs/
For New Content
create_file /home/claude/doc.md "content..."
markdownlint-cli2 --fix /home/claude/doc.md
markdownlint-cli2 /home/claude/doc.md
# Fix remaining issues if any
cp /home/claude/doc.md /mnt/user-data/outputs/
Configuration
Create .markdownlint.json to customize rules:
{
"default": true,
"MD013": { "line_length": 120 },
"MD033": false
}
Common adjustments:
"MD013": false - Disable line length checking"MD013": { "line_length": 120 } - Increase limit to 120"MD013": { "code_blocks": false } - Exclude code blocks"MD033": false - Allow HTML"MD041": false - Don't require first line header
Config file search order:
.markdownlint-cli2.jsonc.markdownlint-cli2.yaml.markdownlint.jsonc / .markdownlint.json.markdownlint.yaml / .markdownlint.yml
Reporting to User
Provide clear summary of fixes:
✅ Markdown linting complete!
Initial: 18 errors
After auto-fix: 4 errors
Manual fixes:
• MD025: Converted 2 H1 headers to H2
• MD036: Replaced bold with proper header
• MD013: Wrapped long line
Final: 0 errors
Error Count Interpretation
Before auto-fix:
- 0-5: Minor issues
- 6-15: Moderate issues
- 16+: Significant issues
After auto-fix:
- 0-2: Excellent
- 3-5: Typical
- 6+: Check if config needed
Common Fix Patterns
# Multiple H1s - analyze structure first
# If sections: convert to H2
str_replace "# Introduction" → "## Introduction"
# If subsections: convert to H3
str_replace "# Details" → "### Details"
# Emphasis as headers - determine appropriate level
str_replace "**Important**" → "## Important"
str_replace "_Note_" → "### Note"
# Long lines - break at natural points
# After conjunctions: and, but, or
# After punctuation: , . ;
# Preserve URLs on single line
Troubleshooting
Auto-fix not working:
# Check file exists
view /path/to/file.md
# Verify permissions
ls -l /path/to/file.md
# Use absolute path
markdownlint-cli2 --fix /full/path/to/file.md
Too many errors after auto-fix:
# Create relaxed config
echo '{"MD013": false, "MD041": false}' > .markdownlint.json
markdownlint-cli2 --config .markdownlint.json --fix file.md
Specific rule causing issues:
- Disable in config:
"MD013": false
- Or adjust parameters:
"MD013": { "line_length": 120 }
When NOT to Lint
Skip linting when:
- Code examples intentionally violate rules
- Embedded HTML/JSX required (disable MD033)
- Generated docs with different conventions
- Legacy docs where changes break references
Use custom config to disable problematic rules.
Quick Rule Reference
Most common rules Claude will encounter:
- MD001 - Header increment by one level
- MD004 - Consistent list markers
- MD009 - No trailing spaces
- MD010 - No hard tabs
- MD012 - No multiple blank lines
- MD013 - Line length (default: 80)
- MD018 - Space after # in headers
- MD022 - Blank lines around headers
- MD025 - Single H1 only
- MD031 - Blank lines around code
- MD032 - Blank lines around lists
- MD034 - Bare URLs in <>
- MD036 - No emphasis as headers
- MD040 - Language for code blocks
Full rule documentation: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md