Markdownlint Skill

This skill provides expertise in using markdownlint-cli2, a fast and flexible linting tool for Markdown files that helps maintain consistent formatting and catches common issues.

About Markdownlint

Markdownlint is a Node.js-based tool that checks Markdown files against a set of configurable rules to enforce consistent style and catch syntax errors. The CLI tool (markdownlint-cli2) is built on top of the markdownlint library and provides enhanced performance and configuration options.

Key Capabilities

• Linting: Check Markdown files against style rules
• Auto-fixing: Automatically fix many common Markdown issues
• Configuration: Customizable rules via multiple configuration formats
• Glob Support: Process multiple files using glob patterns
• Cross-platform: Works consistently across UNIX and Windows
• Fast: Efficient processing of multiple Markdown files

When to Use This Skill

Use this skill when users:

• Need to format or clean Markdown files
• Want to enforce Markdown style consistency across a project
• Need to validate Markdown syntax
• Want to identify and fix Markdown issues automatically
• Need to lint Markdown files as part of CI/CD pipelines
• Ask about Markdown best practices or style rules
• Want to configure custom Markdown linting rules

Project-Specific Configuration

IMPORTANT: This project uses .markdownlint.yaml for configuration. Always follow these project rules:

Key Project Rules

• MD040 (fenced-code-language): ALWAYS specify a language for code fences. Never use plain ``` without a language identifier.
  • ✅ Good: ```bash, ```python, ```json
  • ❌ Bad: ``` (no language specified)
• MD007 (unordered-list-indent): Use 2-space indentation for lists
• MD033 (no-inline-html): Disabled - inline HTML is allowed
• MD041 (first-line-h1): Disabled - files don't need to start with H1
• MD013 (line-length): Disabled - no line length restrictions
• MD024 (no-duplicate-heading): Siblings only - duplicate headings allowed under different parents
• MD038 (no-space-in-code): Disabled
• MD036 (no-emphasis-as-heading): Disabled

When fixing or creating markdown files in this project, always ensure compliance with these rules.

How to Use This Skill

Basic Markdownlint Workflow

The basic command pattern is:

markdownlint-cli2 [glob patterns] [options]

Common Operations

Linting Files

Check a single Markdown file:

markdownlint-cli2 README.md

Check multiple files with glob patterns:

markdownlint-cli2 "**/*.md"
markdownlint-cli2 "docs/**/*.md"
markdownlint-cli2 "*.md" "docs/**/*.md"

Check all Markdown files in the current directory (dot-only glob):

markdownlint-cli2 .
# This is automatically mapped to: markdownlint-cli2 "*.{md,markdown}"

Check all Markdown files recursively:

markdownlint-cli2 "**"

Auto-fixing Issues

Fix issues automatically where possible:

markdownlint-cli2 --fix "**/*.md"
markdownlint-cli2 --fix README.md

The --fix option will modify files in place to resolve fixable issues.

Excluding Files/Directories

Exclude directories using negated patterns (use # for cross-platform compatibility):

markdownlint-cli2 "**/*.md" "#node_modules" "#vendor"
markdownlint-cli2 "**/*.md" "#**/node_modules"

Note: On UNIX shells, use # instead of ! for better compatibility with double-quoted arguments.

Using Configuration Files

Markdownlint will automatically detect configuration files in the following order:

• .markdownlint-cli2.jsonc
• .markdownlint-cli2.yaml
• .markdownlint-cli2.cjs or .markdownlint-cli2.mjs
• .markdownlint.jsonc or .markdownlint.json
• .markdownlint.yaml or .markdownlint.yml
• .markdownlint.cjs or .markdownlint.mjs
• package.json (under markdownlint-cli2 key)

Specify a custom configuration file:

markdownlint-cli2 --config .markdownlint-custom.json "**/*.md"

Working with stdin

Process input from standard input:

cat README.md | markdownlint-cli2 -
echo "# Hello World" | markdownlint-cli2 -

Literal File Paths

Use : prefix to specify literal file paths (bypassing glob expansion):

markdownlint-cli2 ":path/to/file.md"

Configuration

Basic Configuration File

Create a .markdownlint.json file:

{
  "default": true,
  "MD013": false,
  "MD033": false
}

Or a .markdownlint-cli2.jsonc file with comments:

{
  // Use default rules
  "config": {
    "default": true,
    // Disable line length rule
    "MD013": false,
    // Allow inline HTML
    "MD033": false,
    // Customize list indentation
    "MD007": {
      "indent": 2
    }
  },
  // Files to ignore
  "globs": ["**/*.md"],
  "ignores": ["node_modules", "CHANGELOG.md"]
}

Common Rules

Common markdownlint rules (prefix with MD):

• MD001: Heading levels should increment by one
• MD003: Heading style (consistent, atx, setext)
• MD004: Unordered list style
• MD007: Unordered list indentation
• MD009: Trailing spaces
• MD010: Hard tabs
• MD012: Multiple consecutive blank lines
• MD013: Line length (often disabled for flexibility)
• MD022: Headings should be surrounded by blank lines
• MD024: Multiple headings with the same content
• MD025: Multiple top-level headings
• MD031: Fenced code blocks should be surrounded by blank lines
• MD032: Lists should be surrounded by blank lines
• MD033: Inline HTML (often disabled when HTML is needed)
• MD034: Bare URLs
• MD040: Fenced code blocks should have a language ⚠️ CRITICAL: Always specify language in this project
• MD041: First line should be a top-level heading

Disable Rules Inline

Disable rules for specific sections using HTML comments:

<!-- markdownlint-disable MD013 -->
This is a very long line that would normally trigger MD013 but won't because the rule is disabled.
<!-- markdownlint-enable MD013 -->

<!-- markdownlint-disable-next-line MD033 -->
<div>This HTML is allowed</div>

<!-- markdownlint-disable-file MD013 -->
Disable a rule for the entire file

Cross-Platform Best Practices

For maximum compatibility across platforms:

1. Quote glob patterns: Always use double quotes around patterns

   markdownlint-cli2 "**/*.md" "#node_modules"
   

2. Use # for negation: Instead of ! which can cause shell issues

   markdownlint-cli2 "**/*.md" "#vendor"
   

3. Use forward slashes: Always use / for path separators (works on all platforms)

   markdownlint-cli2 "docs/**/*.md"
   

4. Stop processing options: Use -- to treat remaining arguments as literals

   markdownlint-cli2 -- "file-with-special-chars.md"
   

Common Workflows

Format All Markdown in a Project

markdownlint-cli2 --fix "**/*.md" "#node_modules" "#vendor"

Check Only Docs Directory

markdownlint-cli2 "docs/**/*.md"

CI/CD Integration

Add to your CI pipeline to enforce Markdown standards:

# Fail build if any issues found
markdownlint-cli2 "**/*.md" "#node_modules"

Pre-commit Hook

Lint staged Markdown files before commit:

#!/bin/sh
markdownlint-cli2 $(git diff --cached --name-only --diff-filter=ACM | grep '\.md$')

Fix and Review

Fix issues but review changes before committing:

# Create a backup first
git add .
git commit -m "Backup before markdownlint fix"

# Apply fixes
markdownlint-cli2 --fix "**/*.md"

# Review changes
git diff

# Commit if satisfied or reset if not
git add .
git commit -m "Apply markdownlint fixes"

Troubleshooting

No Files Matched

If markdownlint reports no files matched:

• Check that glob patterns are properly quoted
• Verify file extensions (.md vs .markdown)
• Ensure negated patterns aren't excluding everything

Too Many Issues

If you're overwhelmed by issues on an existing project:

1. Start by fixing auto-fixable issues: markdownlint-cli2 --fix "**/*.md"
2. Review the most common violations
3. Disable problematic rules initially and gradually enable them
4. Focus on high-priority rules first (headings, lists, code blocks)

Configuration Not Loading

If your configuration isn't being applied:

• Check file name matches expected patterns
• Validate JSON/YAML syntax
• Use --config to explicitly specify the file
• Check for syntax errors in configuration

Best Practices

1. Start with defaults: Begin with all default rules enabled and disable only what's necessary
2. Use auto-fix liberally: Many issues are mechanical and safe to auto-fix
3. Configure line length carefully: MD013 (line length) is often disabled or set to a high value
4. Allow necessary HTML: Disable MD033 if your Markdown intentionally includes HTML
5. Document exceptions: Use inline comments to explain why rules are disabled
6. Commit configuration: Keep .markdownlint.json in version control for consistency
7. Run early and often: Integrate linting into your development workflow
8. Review auto-fixes: Always review changes from --fix before committing

Installation

Markdownlint-cli2 can be installed via:

• npm: npm install -g markdownlint-cli2
• yarn: yarn global add markdownlint-cli2
• pnpm: pnpm add -g markdownlint-cli2
• Homebrew: brew install markdownlint-cli2

Verify installation:

markdownlint-cli2 --help

Resources

• Official repository: https://github.com/DavidAnson/markdownlint-cli2
• Markdownlint rules: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
• Configuration schema: https://github.com/DavidAnson/markdownlint-cli2#configuration