About Markdown Linter

Lint markdown files for style consistency, formatting issues, and best practices. Part of the DevTools Surf developer suite. Browse more tools in the API / Config collection.

Use Cases

• Enforce consistent heading hierarchy, list formatting, and code fence style across a documentation repository.
• Catch broken links, missing blank lines around headings, and overlong lines before pushing to GitHub.
• Validate README files across a multi-repo organization as part of a CI quality gate.
• Check that auto-generated Markdown from a documentation tool follows project style rules.

Tips

• Configure rules per project (heading style, list marker type) and commit the .markdownlint.json to enforce consistency across all contributors.
• Enable the 'no-trailing-spaces' rule — trailing spaces in Markdown create hard line breaks, which are almost never intentional.
• Lint markdown in CI using markdownlint-cli2 — the same rules the linter uses are compatible with the CLI, ensuring local and CI results match.

Fun Facts

• markdownlint, the rule set underlying most Markdown linters, was created by David Anson in 2015. It has over 56 configurable rules, the most comprehensive of any Markdown quality tool.
• ATX-style headings (# Heading) and Setext-style headings (Heading followed by === or ---) produce identical HTML but are stylistically incompatible in a codebase — one of the most commonly-configured lint rules.
• GitHub's documentation team maintains a Markdown style guide that bans 76 specific patterns, including bare URLs, inline HTML (except for tables), and heading punctuation — demonstrating how opinionated large teams become about Markdown consistency.

FAQ

Which rules are enabled by default?

The default ruleset enables MD001 (heading increment), MD010 (no hard tabs), MD022 (blank lines around headings), MD031 (blank lines around code fences), and MD041 (first line is an H1). All are configurable.

Can I fix lint errors automatically?

Yes — rules with clear automatic fixes (trailing spaces, multiple blank lines, missing final newline) are auto-fixed. Subjective style rules require manual review.

Is it compatible with markdownlint-cli2?

Yes — export your configuration as .markdownlint.json and use it with markdownlint-cli2 in CI. The same rules produce the same results in both the tool and the CLI.