Markdownlint — Lint Markdown for AI Content Quality

What it is

Markdownlint is a Node.js-based linter for Markdown files with 50+ configurable rules. It catches formatting inconsistencies, structural issues, and style violations in markdown content. The tool is available as a CLI (markdownlint-cli2), VS Code extension, and GitHub Action.

It is particularly useful for teams maintaining markdown-based AI tool configurations like CLAUDE.md, .cursorrules, and README files. As AI-generated documentation becomes more common, consistent markdown formatting prevents rendering issues and improves readability across platforms.

How it saves time or tokens

Markdownlint automates style enforcement that would otherwise require manual review. Instead of scanning documents for inconsistent heading levels, trailing spaces, or missing blank lines, you run a single command and get a list of violations. This is especially valuable when AI assistants generate markdown, as LLMs sometimes produce inconsistent formatting that compiles but renders poorly. Estimated token usage for this workflow is around 3,800 tokens.

How to use

1. Install the CLI: npm install -g markdownlint-cli2.
2. Run the linter: markdownlint-cli2 '*/.md' to check all markdown files.
3. Configure rules in .markdownlint.json or .markdownlint-cli2.jsonc to match your project standards.
4. Add to CI: use the GitHub Action or pre-commit hook to catch issues before merge.

Example

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

# Lint all markdown files
markdownlint-cli2 '**/*.md'

# Fix auto-fixable issues
markdownlint-cli2 --fix '**/*.md'

# Lint only CLAUDE.md and README
markdownlint-cli2 CLAUDE.md README.md

Related on TokRepo

• AI tools for documentation -- find tools for maintaining and generating technical docs.
• AI tools for coding -- explore linters, formatters, and developer productivity tools.

Common pitfalls

• Running with default rules may flag too many issues in existing projects. Start by disabling noisy rules like MD013 (line length) and gradually enable stricter checks.
• The VS Code extension and CLI may use different rule versions. Pin the same version in both to avoid conflicting results.
• Markdownlint checks formatting, not content accuracy. It will not catch factual errors or broken external links -- use a separate link checker for that.