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

mdlint migrate

Migrate a configuration from another Markdown tool to mdlint.toml. Currently supported sources (--from): markdownlint-cli2 (default).

Usage: mdlint migrate [OPTIONS] [INPUT]

Arguments:
  [INPUT]                          Path to the configuration to migrate (auto-detected if omitted)

Options:
      --from <SOURCE>               Tool to migrate the configuration from [default: markdownlint-cli2]
      --output <PATH>               Output path for the generated config [default: mdlint.toml]
      --force                       Overwrite the output file if it already exists
      --dry-run                     Print the generated config without writing it
  -h, --help                        Print help

markdownlint-cli2

Supports .markdownlint-cli2.{json,jsonc,yaml,yml} and standalone .markdownlint.{json,jsonc,yaml,yml} rule configs, and falls back to the "markdownlint-cli2" field in package.json if no dedicated config file is found. Rule names and their common aliases (e.g. line-length for MD013) are both recognized. The gitignore, noInlineConfig, and frontMatterPattern cli2 options map onto mdlint's equivalent gitignore, no_inline_config, and front_matter settings. .cjs/.mjs configs are evaluated with a Node.js runtime when one is found on PATH (the same thing markdownlint-cli2 itself would do when loading them), correctly resolving require(), spread syntax, and computed values. If Node isn't available, mdlint falls back to a best-effort text scrape and warns that dynamic values may not have been resolved; if a config can't be parsed either way, migration fails with a message asking you to export it with console.log(JSON.stringify(config)) and migrate the resulting JSON file instead. Rules with no mdlint implementation, and cli2-specific fields with no mdlint equivalent (globs, customRules, outputFormatters), are skipped with a warning rather than failing the migration.

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

# migrate a markdownlint-cli2 config to mdlint.toml (auto-detected)
mdlint migrate

# migrate a specific config file to a custom output path
mdlint migrate --from markdownlint-cli2 .markdownlint-cli2.jsonc --output mdlint.toml

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

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

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

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.

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