mdlint

A Python Markdown linter that checks files for style and formatting violations.

• 50+ built-in rules covering headings, lists, whitespace, links, code blocks, and more
• Configurable via .mdlint.toml or pyproject.toml with per-rule settings
• Multiple output formats including human-readable terminal output and JSON
• Gitignore-aware file discovery that respects .gitignore patterns
• Auto-fix support via --fix to automatically correct fixable violations
• stdin support for integration with editors and CI pipelines
• Built-in rule documentation accessible from the CLI
• Online playground to try mdlint directly in the browser — no installation needed
• Parallel processing of files automatically when checking large projects
• Compatible with existing markdownlint rule sets (Ruby and JavaScript implementations)

Installation

uv tool install mdlint
# OR
pip install --user mdlint
# OR run directly
uvx mdlint -h

Requires Python 3.10 or later.

Usage

Lint files or directories

# Lint current directory
mdlint check

# Lint specific files
mdlint check README.md docs/guide.md

# Lint a directory recursively
mdlint check docs/

# Lint from stdin
cat README.md | mdlint check -

Output formats

# Human-readable output (default)
mdlint check docs/

# JSON output
mdlint check --format json docs/

Auto-fix violations

# Fix violations in-place
mdlint check --fix docs/

# Fix stdin and output result to stdout
cat README.md | mdlint check --fix -

Not all rules support auto-fixing. When --fix is used, fixable violations are corrected automatically and any remaining unfixable violations are still reported. The rules index in the documentation indicates which rules are fixable.

View rule documentation

# List all rules
mdlint rule

# View specific rule details
mdlint rule MD001

# Include valid/invalid examples
mdlint rule MD003 --show-examples

Rule compatibility matrix

The following table shows rule availability across mdlint and the Ruby and JavaScript markdownlint implementations. The rule behavior is mostly consistent with that of the markdownlint projects (slight preference to the JavaScript implementation), but may differ slightly over time as the project evolves.

Configuration

Configuration file

Create .mdlint.toml in your project root:

# Select specific rules to run (default: all rules)
select = ["MD001", "MD003", "MD041"]

# Ignore specific rules (subtracted from select)
ignore = ["MD041"]

# Rule-specific configuration
[rules.MD041]
level = 2  # Expect first heading to be h2

[rules.MD003]
style = "atx"  # atx | atx_closed | setext | setext_with_atx | consistent

[rules.MD013]
line_length = 120
code_blocks = false

Or add to pyproject.toml:

[tool.mdlint]
ignore = ["MD041"]

[tool.mdlint.rules.MD003]
style = "atx"

Rule selection

The select and ignore options work together:

• select establishes the baseline set of rules (defaults to all rules if omitted)
• ignore subtracts from the select set

Examples:

# Run all rules except MD041
ignore = ["MD041"]

# Run only MD001 and MD003
select = ["MD001", "MD003"]

# Run MD001, MD003-MD005, but skip MD004
select = ["MD001", "MD003", "MD004", "MD005"]
ignore = ["MD004"]  # Alternatively, omit from select list

Command-line options

# Use a specific config file
mdlint check --config path/to/config.toml

# Inline configuration
mdlint check --config "MD003.style='atx'"

# Select specific rules (replaces config select list)
mdlint check --select MD001 --select MD003

# Ignore specific rules (replaces config ignore list)
mdlint check --ignore MD002

# Add to existing select/ignore lists
mdlint check --extend-select MD004 --extend-ignore MD005

# Disable .gitignore and .ignore patterns
mdlint check --no-ignore

# Verbose output (show files being processed)
mdlint check --verbose

Exit codes

License

MIT