Skip to main content

mdlint

PyPI version PyPI - Python Version CI License PyPI - Downloads Docs

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.11 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.

Rule(s) mdlint Ruby markdownlint JS markdownlint Notes
MD001 ✓ ✓ ✓
MD002 — ✓ — Not implemented (use MD041)
MD003–MD005 ✓ ✓ ✓
MD006 — ✓ — Not implemented (use MD007)
MD007 ✓ ✓ ✓
MD008 — — — Not implemented
MD009–MD014 ✓ ✓ ✓
MD015–MD017 — — — Not implemented
MD018–MD041 ✓ ✓ ✓
MD042–MD045 ✓ — ✓
MD046–MD047 ✓ ✓ ✓
MD048–MD056 ✓ — ✓
MD057 — — — Not implemented
MD058–MD060 ✓ — ✓

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"

mdlint uses a single configuration file: the one passed with --config, or else the first one found by searching from the current directory upward (.mdlint.toml before pyproject.toml in each directory). Settings from other files are not merged in.

Rules can be named by ID or by name in any case, for example MD013, md013, or line-length; this applies to select, ignore, [rules.<rule>] sections, and the command-line options. Unknown rules, unknown options, and values of the wrong type are reported as errors (exit code 2).

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 MD041

# 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

Code Meaning
0 No violations and no errors
1 Violations found, even if some files could not be read
2 Invalid configuration, unknown rule or missing path; or files could not be read and no violations were found

License

MIT

Metadata

Release files for mdlint 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mdlint 0.4.0
File Size Uploaded Provenance Actions
mdlint-0.4.0.tar.gz 111.4 kB With provenance Details for mdlint-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mdlint 0.4.0
File Interpreter ABI Platform Actions
mdlint-0.4.0-py3-none-any.whl Python 3 none any Details for mdlint-0.4.0-py3-none-any.whl

Total release size: 266.7 kB

Release files / mdlint-0.4.0.tar.gz

Download URL mdlint-0.4.0.tar.gz
Size 111.4 kB
Tags Source
SHA-256 checksum
How to use checksums
fecd3048014259ab1e4f80159d8ba720c709a75a8cfe6054e07a1e22ca021c59
BLAKE2b-256 checksum
How to use checksums
e3a056d7f29c64b8051b82879f3d6672a56752e6b9cb184546d2ef60dfac86b5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / mdlint-0.4.0-py3-none-any.whl

Download URL mdlint-0.4.0-py3-none-any.whl
Size 155.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8e60792a0bb4b691a2d3dd1755f762f9984c481c4ae96f8593655c04e8c5c3b9
BLAKE2b-256 checksum
How to use checksums
76f1dcb67fddf60dd0401b1af1165991c8644189e03ee5f194de2c33e143ddd9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for mdlint 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mdlint-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page