Markdown Linter
Lint markdown files for heading hierarchy, broken links, missing alt text, formatting issues, inconsistent list markers, trailing whitespace, and line length.
Get the CLI Tool
Run the markdown linter locally as an MCP server, or try it online below.
npx @clinetools/markdown-linter
- Heading hierarchy checks — detects skipped levels and multiple H1s
- Broken link detection — catches empty links and malformed syntax
- Missing alt text — flags images without accessibility descriptions
- List marker consistency — detects mixed *, -, and + markers
- Zero config — just run with npx
How to Use It
Three ways to lint your markdown files — pick the one that fits your workflow.
Try Online
Use the interactive demo below to paste markdown content and lint it — no install needed.
Use via CLI
Run as a local MCP server and connect any MCP-compatible client.
Add to Cline / Claude Code
Add the tool to your MCP settings for instant access from your AI assistant.
MCP Client Configuration (Cline)
{
"mcpServers": {
"markdown-linter": {
"command": "npx",
"args": ["@clinetools/markdown-linter"]
}
}
}
Claude Code Configuration
# In your project's .mcp.json:
{
"mcpServers": {
"markdown-linter": {
"command": "npx",
"args": ["@clinetools/markdown-linter"]
}
}
}
Example: Lint a Markdown File
// Call the tool with a file path:
lint_markdown({ path: "README.md" })
// Output:
{
"file": "README.md",
"issues": [
{
"line": 12,
"rule": "heading-hierarchy",
"severity": "warning",
"message": "Heading level skipped: H1 -> H3",
"suggestion": "Use H2 before H3"
}
],
"summary": { "errors": 0, "warnings": 1, "info": 0 }
}
Example: "Fix my README" Prompt
// Prompt to your AI agent:
"Lint my README.md and fix any issues you find"
// The agent calls:
lint_markdown({ path: "README.md" })
// Output:
{
"file": "README.md",
"issues": [
{
"line": 3,
"rule": "no-alt-text",
"severity": "warning",
"message": "Image missing alt text: ",
"suggestion": "Add descriptive alt text: "
},
{
"line": 8,
"rule": "inconsistent-lists",
"severity": "warning",
"message": "Mixed list markers: found '+' but document uses '-'",
"suggestion": "Use '-' consistently for unordered lists"
}
]
}
// The agent then fixes both issues automatically
Try It Online
Paste markdown below and lint it instantly. Or try one of our demo scenarios.
Paste Markdown to Lint
Checks headings, links, alt text, lists, whitespace, and more
Paste markdown and click Lint Markdown to see results.
Issues Found
Why Markdown Linting Matters
Clean, consistent markdown improves accessibility, collaboration, and portability across every renderer.
Heading Hierarchy
Screen readers use heading levels to build a document outline. Skipping from H1 to H3 breaks navigation for assistive technology users and hurts SEO. Proper nesting creates a logical, accessible structure.
Alt Text Matters
Images without alt text are invisible to screen readers and search engines. Descriptive alt text makes your documentation accessible to everyone and improves discoverability through image search.
Consistent Formatting
Mixing list markers (*, -, +) and inconsistent spacing creates noisy diffs and confuses collaborators. Consistent formatting makes code reviews faster and documentation easier to maintain.
Link Hygiene
Broken links, empty link targets, and bare URLs hurt credibility and user experience. Validating link syntax catches issues before readers hit dead ends in your documentation.
Markdown Portability
GitHub, GitLab, VS Code, Docusaurus, and other renderers handle edge cases differently. Clean markdown with no trailing whitespace, proper blank lines, and valid syntax renders correctly everywhere.
Need Documentation Quality Gates?
Our Pro plan includes automated markdown linting across your entire repository with CI integration.
View Plans