Markdownlint Skill

Markdownlint Skill

Contents

• Markdownlint Skill
  • 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:

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

1. Run lint check: markdownlint-cli2 "**/​*.md"
2. Review reported issues
3. Apply auto-fix: markdownlint-cli2 --fix "**/​*.md"
4. Re-run lint to verify: markdownlint-cli2 "**/​*.md"
5. Review changes: git diff
6. Commit when satisfied

Safe Fix with Backup

1. Stage current state: git add .
2. Create backup commit: git commit -m "Backup before markdownlint fix"
3. Apply fixes: markdownlint-cli2 --fix "**/​*.md"
4. Review changes: git diff
5. 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 (.md vs .markdown)
• Ensure negated patterns don't exclude everything

Too Many Issues

1. Start with auto-fix: markdownlint-cli2 --fix "**/​*.md"
2. Disable problematic rules temporarily
3. Address remaining issues incrementally

Configuration Not Loading

• Verify configuration file name matches expected patterns
• Validate JSON/​YAML syntax
• Use --config to 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