Markdownlint — Lint Markdown for AI Content Quality

What is Markdownlint?

Markdownlint is a Node.js-based linter for Markdown files with 50+ configurable rules. It catches formatting inconsistencies, broken links, and structural issues — ensuring clean, consistent markdown in your CLAUDE.md, .cursorrules, README files, and AI-generated documentation.

Answer-Ready: Markdownlint is a Node.js markdown linter with 50+ rules for consistent formatting. Lint CLAUDE.md, .cursorrules, README files, and AI-generated docs. Available as CLI, VS Code extension, and GitHub Action. 5k+ GitHub stars.

Best for: Developers maintaining markdown-based AI tool configurations. Works with: VS Code, JetBrains, GitHub Actions, any CI/CD. Setup time: Under 1 minute.

Core Features

1. 50+ Built-In Rules

2. Configuration

// .markdownlint.json
{
  "MD013": { "line_length": 120 },
  "MD033": false,
  "MD041": false,
  "MD024": { "siblings_only": true }
}

3. VS Code Integration

Install the markdownlint extension:

• Real-time linting as you type
• Quick fixes for common issues
• Works on CLAUDE.md, .cursorrules, README.md

4. CI/CD Integration

# .github/workflows/lint.yml
name: Lint Markdown
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: DavidAnson/markdownlint-cli2-action@v19
        with:
          globs: "**/*.md"

5. Fix Automatically

# Auto-fix fixable issues
markdownlint-cli2 --fix "**/*.md"

6. Ignore Patterns

# .markdownlintignore
node_modules/
dist/
CHANGELOG.md

Use with AI Tool Configs

CLAUDE.md Linting

# Lint your Claude Code config
markdownlint-cli2 CLAUDE.md

.cursorrules Linting

# Treat .cursorrules as markdown
markdownlint-cli2 .cursorrules

AI-Generated Content

# Lint AI-generated docs before committing
markdownlint-cli2 --fix docs/**/*.md

Common Fixes

FAQ

Q: Does it work with MDX? A: Partially — it handles standard markdown syntax. JSX blocks may trigger false positives; disable specific rules as needed.

Q: Can I create custom rules? A: Yes, via the plugin API. Write rules as Node.js modules.

Q: Is there a pre-commit hook? A: Yes, use with husky or lefthook for pre-commit linting.