markdownlint-rs 0.3.21

Opinionated Markdown formatter and linter

mdlint

An opinionated Markdown formatter and linter, written in Rust.

What ruff did for Python and gofmt did for Go, mdlint aims to do for Markdown: enforce a single, consistent canonical style so that style debates disappear and diffs stay meaningful. As AI coding agents increasingly read and write Markdown, well-structured files matter more than ever. Run mdlint format and stop thinking about it.

Project Status: Active development, but no one's top priority.

Features

• Formatter first: mdlint format rewrites files to a canonical style — no configuration required
• Linter second: mdlint check reports violations; fixable rules are auto-corrected by mdlint format or mdlint check --fix
• Fast: written in Rust for performance
• Portable: single, small, 0-dependency binary (Linux x86_64/ARM64, macOS Intel/Apple Silicon, Windows)
• Git-aware: respects .gitignore files by default

Quickstart

No install needed — run directly with uvx:

uvx markdownlint-rs check   # lint all Markdown files in the current directory
uvx markdownlint-rs format  # format all Markdown files in the current directory

Installation

mdlint comes packaged in many forms: static binaries, from a Python wrapper, from an NPM wrapper, and in a Docker container! More ways of installing are in the works, but here's the current list:

:warning: Be aware: mdlint is the executable name, but most package names are still markdownlint-rs!

# cargo
cargo install markdownlint-rs

# uv
uv tool install markdownlint-rs

# or as a project dependency
uv add --dev markdownlint-rs

# pip
pip install markdownlint-rs

# npm project dependency
npm install --save-dev markdownlint-rs

# Docker (linux/amd64 and linux/arm64) - hosted on both DockerHub and GitHub Container Registry
docker run --rm -v "$PWD:/workspace" ghcr.io/swanysimon/mdlint:latest check
docker run --rm -v "$PWD:/workspace" simonswanson/mdlint:latest       format

Pre-built binaries for Linux (x86_64/ARM64, glibc and musl), macOS (Intel/Apple Silicon), and Windows are available on the releases page. A Homebrew formula is planned.

pre-commit framework

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/swanysimon/mdlint
    # use the latest release tag
    rev: v0.3.21
    hooks:
      - id: mdlint-format
      - id: mdlint-check

Or use additional arguments, e.g. to disable auto-fix:

    hooks:
      - id: mdlint-format
        args: [--check]
      - id: mdlint-check
        args: [--no-fix]

Usage

mdlint check

Lint Markdown files and report issues.

Usage: mdlint check [OPTIONS] [FILES]...

Arguments:
  [FILES]...                       Files or directories to check (defaults to current directory)

Options:
      --fix                        Apply auto-fixes where possible
      --no-fix                     Disable auto-fix even if enabled in config
      --output-format <FORMAT>     Output format [default: default] [possible values: default, json]
      --select <RULE_CODE>,...     Enable only the specified rules (comma-separated, or ALL)
      --ignore <RULE_CODE>,...     Disable the specified rules (comma-separated)
      --exclude <PATH>             Exclude files or directories from analysis
      --no-respect-ignore          Do not respect .gitignore files
      --parallel                   Lint files in parallel (experimental)
  -h, --help                       Print help

Global options:
      --config <CONFIG>            Path to TOML configuration file
      --no-config                  Ignore all configuration files
  -v, --verbose                    Enable verbose logging
  -q, --quiet                      Print diagnostics only
  -s, --silent                     Disable all logging (exit code still reflects result)
      --color <COLOR>              Control colors in output [default: auto] [possible values: auto, always, never]

mdlint format

Format Markdown files with opinionated style.

Usage: mdlint format [OPTIONS] [FILES]...

Arguments:
  [FILES]...                       Files or directories to format (defaults to current directory)

Options:
      --check                      Check formatting only; do not modify files (exits 1 if any file would change)
      --exclude <PATH>             Exclude files or directories
      --no-respect-ignore          Do not respect .gitignore files
  -h, --help                       Print help

Examples

# check all Markdown files and apply auto-fixes
mdlint check --fix

# check specific files
mdlint check README.md docs/

# check with JSON output (for CI integrations)
mdlint check --output-format json

# enable only specific rules
mdlint check --select MD001,MD022

# disable specific rules for this run
mdlint check --ignore MD013,MD033

# format all files
mdlint format

# verify formatting without modifying files (for CI)
mdlint format --check

# format specific files
mdlint format README.md docs/

# use a custom config file
mdlint check --config path/to/mdlint.toml

# ignore all config files
mdlint check --no-config

Configuration

mdlint uses TOML configuration files, discovered by searching upward from the current directory. The tool searches for these files in order (first found wins per directory level), walking up from the current directory:

1. mdlint.toml
2. .mdlint.toml

Planned: package.json and pyproject.toml support.

Configuration hierarchy

Configs are discovered by walking up the directory tree. Scalar values from closer configs override those farther away; arrays are extended. Priority order (highest to lowest):

1. --config flag on the CLI
2. mdlint.toml / .mdlint.toml in the current directory
3. Config files in parent directories (walking up to the filesystem root)
4. Built-in defaults

Global options

Option	Default	Description
default_enabled	true	Enable all rules unless explicitly disabled; false to enable only configured rules.
gitignore	true	Respect .gitignore files when discovering Markdown files.
no_inline_config	false	Ignore all <!-- mdlint-disable --> comments.
fix	true	mdlint check automatically applies all fixable violations; equivalent to passing --fix on the CLI.
front_matter	auto	Front matter delimiter. Auto-detects --- (YAML) and +++ (TOML). Set to "---" to accept YAML only.
exclude	[]	Paths/glob patterns excluded from discovery; merged with any --exclude CLI flags.
custom_rules	[]	Paths to external rule modules (future feature).

Rule configuration

Each rule is configured in its own [rules.MDxxx] section. Providing any parameter enables the rule. Use enabled = false to explicitly disable a rule when default_enabled = true.

# disable a rule
[rules.MD013]
enabled = false

# configure parameters (also enables the rule)
[rules.MD013]
line_length = 100
code_blocks = false

# combine enabled flag with parameters
[rules.MD044]
enabled = true
names = ["JavaScript", "TypeScript", "GitHub"]

See mdlint.default.toml for every option with its default value.

Inline configuration

Rules can be suppressed for specific lines using HTML comments:

<!-- mdlint-disable-next-line MD013 -->
This line may be longer than the configured limit.

<!-- mdlint-disable MD033 -->
<div>Raw HTML block that needs to stay as-is</div>
<!-- mdlint-enable MD033 -->

Comment	Effect
<!-- mdlint-disable MD001 -->	Disable rule from this line onward
<!-- mdlint-enable MD001 -->	Re-enable rule from this line onward
<!-- mdlint-disable-next-line MD001 -->	Disable rule for the next line only
<!-- mdlint-disable -->	Disable all rules from this line onward
<!-- mdlint-enable -->	Re-enable all rules

Multiple rules: <!-- mdlint-disable MD001 MD013 --> — space-separate rule codes. Set no_inline_config = true in mdlint.toml to ignore all inline comments project-wide.

Exit Codes

Code	Meaning
0	Success — no lint violations (or files are already formatted with format --check)
1	Lint violations found (or files need formatting with format --check)
2	Runtime error (invalid config, file not found, etc.)

Rules

Rules marked ✓ in the Fix column are auto-corrected by mdlint check --fix and mdlint format. Rules without ✓ are reported by mdlint check only and require manual correction. Default shows mdlint's configured default for the rule's key parameter(s); markdownlint shows the original markdownlint default where it differs from mdlint's. — means the rule has no configurable parameters.

Rule	Fix	Default	markdownlint	Description	Notes
MD001		—	—	Heading levels should only increment by one level at a time	Catches accidental heading skips (e.g. h1 → h3 without h2)
MD003		atx	consistent	Heading style should be consistent throughout the document	Config: style — atx (# Heading), setext, atx_closed, consistent
MD004	✓	dash	consistent	Unordered list style should be consistent	Config: style — dash, asterisk, plus, consistent
MD005		—	—	Inconsistent indentation for list items at the same level	Catches copy-paste errors where sibling items have different indentation
MD007		indent: 2		Unordered list indentation	Config: indent — spaces per nesting level
MD009	✓	br_spaces: 2		Trailing spaces	Two trailing spaces mean a hard line break; format converts them to \ syntax. Config: br_spaces, strict
MD010	✓	code_blocks: true		Hard tabs	Tabs render inconsistently across editors; format replaces with spaces. Config: code_blocks
MD011		—	—	Reversed link syntax	Catches the common typo of swapped parentheses and brackets; should always be enabled
MD012	✓	maximum: 1		Multiple consecutive blank lines	Config: maximum — max consecutive blank lines allowed
MD013		line: 120, heading: 80	line: 80	Line length	mdlint raises the line limit to 120 to better fit URLs and long identifiers. Config: line_length, heading_line_length, code_blocks, tables, headings
MD014	✓	—	—	Dollar signs used before commands without showing output	$-prefixed shell commands cannot be copy-pasted; omit the $ prompt
MD018	✓	—	—	No space after hash on atx style heading	#Title renders inconsistently; format inserts the required space
MD019	✓	—	—	Multiple spaces after hash on atx style heading	# Title → # Title; format normalises to one space
MD020	✓	—	—	No space inside hashes on closed atx style heading	Only relevant if using #Title# style headings
MD021	✓	—	—	Multiple spaces inside hashes on closed atx style heading	Only relevant if using #Title# style headings
MD022	✓	—	—	Headings should be surrounded by blank lines	Required by many renderers for correct parsing; format inserts blank lines
MD023	✓	—	—	Headings must start at the beginning of the line	Indented headings are treated as code or paragraphs in CommonMark
MD024		siblings_only: false		Multiple headings with the same content	Config: siblings_only — set true to flag only duplicates within the same parent heading
MD025		—	—	Multiple top-level headings in the same document	Disable for document fragments that intentionally lack a single top-level title
MD026		".,;:!?。，；：！？"	".,;:!。，；：！"	Trailing punctuation in heading	Headings are labels, not sentences. mdlint additionally disallows ?. Config: punctuation
MD027	✓	—	—	Multiple spaces after blockquote symbol	> text → > text; format normalises
MD028		—	—	Blank line inside blockquote	Blank lines split blockquotes into separate elements in CommonMark; may be intentional
MD029	✓	ordered	one_or_ordered	Ordered list item prefix	mdlint requires sequential numbering. Config: style — ordered (1. 2. 3.), one (all 1s), one_or_ordered
MD030	✓	all: 1		Spaces after list markers	Config: ul_single, ul_multi, ol_single, ol_multi — spaces after marker per context
MD031	✓	—	—	Fenced code blocks should be surrounded by blank lines	Some renderers require blank lines around fences to parse correctly
MD032		—	—	Lists should be surrounded by blank lines	Consistent blank lines around lists improve rendering across processors
MD033		allowed_elements: []		Inline HTML	HTML reduces portability. Config: allowed_elements — add e.g. ["details", "summary"]
MD034		—	—	Bare URL used	Plain URLs don't render as links in all Markdown processors; use [text](url)
MD035	✓	---	consistent	Horizontal rule style	Config: style — ---, ***, ___, consistent
MD036		".,;:!?。，；：！？"		Emphasis used instead of a heading	Bold/italic-only lines won't appear in a table of contents. Config: punctuation
MD037		—	—	Spaces inside emphasis markers	* text * and ** text ** do not render as emphasis in CommonMark
MD038		—	—	Spaces inside code span elements	` text ` is technically valid but inconsistent with expected style
MD039		—	—	Spaces inside link text	[ text ] is valid but inconsistent
MD040		—	—	Fenced code blocks should have a language specified	Language tags enable syntax highlighting. Config: allowed_languages
MD041		level: 1		First line in file should be a top-level heading	Disable for files starting with badges, front matter, or that are document fragments
MD042		—	—	No empty links	[text]() is almost always a mistake
MD043		—	—	Required heading structure	Useful for template-driven documentation; too restrictive for most projects. Config: headings
MD044		names: []		Proper names should have the correct capitalization	Requires configuration to be useful. Config: names, code_blocks
MD045		—	—	Images should have alternate text (alt text)	Alt text is required for accessibility; screen readers depend on it
MD046		fenced	consistent	Code block style	Config: style — fenced, indented, consistent
MD047	✓	—	—	Files should end with a single newline character	POSIX standard; prevents "no newline at end of file" noise in git diffs
MD048		backtick	consistent	Code fence style	Config: style — backtick, tilde, consistent
MD049	✓	asterisk	consistent	Emphasis style should be consistent	Config: style — asterisk, underscore, consistent
MD050	✓	asterisk	consistent	Strong style should be consistent	Config: style — asterisk, underscore, consistent
MD051		—	—	Link fragments should be valid	Broken #anchor links are invisible to parsers but silently break in-page navigation
MD052		—	—	Reference links and images should use a label that is defined	Undefined reference links silently render as plain text instead of a link
MD053		—	—	Link and image reference definitions should be needed	Cleans up leftover link definitions after references are removed
MD054		—	—	Link and image style	Enforces consistent use of inline vs reference link syntax
MD055		leading_and_trailing	consistent	Table pipe style	Config: style — leading_and_trailing, leading_only, trailing_only, no_leading_or_trailing, consistent
MD056		—	—	Table column count	Mismatched column counts cause unpredictable table rendering across processors
MD058		—	—	Tables should be surrounded by blank lines	Blank lines ensure tables are consistently parsed across Markdown processors
MD059		—	—	Link text should be descriptive	"click here" and "read more" are inaccessible; use meaningful link text
MD060		consistent	any	Table column style	mdlint requires a consistent alignment choice. Config: style — consistent, default, left, right, center

Contributing

Contributions are welcome!

Development setup

Prerequisites: mise and Rust. Optionally, Docker is needed for Dockerfile linting. uv is required only if working on the Python package.

git clone https://github.com/swanysimon/mdlint.git
cd mdlint
mise install   # installs prek, tombi, hadolint
cargo build

Code quality

All quality checks run via prek run -a. This must pass before submitting a pull request.

Pull request process

1. Create a feature branch from main
2. Make focused commits with clear messages
3. Add tests for new functionality
4. Run prek run -a and fix any failures
5. Submit a PR with a description of what changed and why

Release process

Releases use cargo-release, which bumps all package manifests in sync and pushes the tag that triggers CI to build, package, and publish everything automatically:

cargo release patch --execute   # or minor / major

Once the tag is pushed, CI verifies manifest versions, builds binaries for all 7 platforms, and publishes to crates.io, PyPI, and npm via trusted publishing (no tokens required).

License

The Unlicense - see LICENSE for details.

Acknowledgments

• markdownlint by David Anson — original rule definitions
• markdownlint-cli2 also by David Anson - most people's first frontend to markdownlint
• mdformat — inspiration for the formatter-first approach
• pulldown-cmark — Markdown parsing

Resources

• Documentation
• Issue Tracker
• Releases
• markdownlint Rules Reference