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.tomlorpyproject.tomlwith per-rule settings - Multiple output formats including human-readable terminal output and JSON
- Gitignore-aware file discovery that respects
.gitignorepatterns - Auto-fix support via
--fixto 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
markdownlintrule 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:
selectestablishes the baseline set of rules (defaults to all rules if omitted)ignoresubtracts 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.