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:

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 (.md vs .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 --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