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