GitHub - akiomik/mado: A fast Markdown linter written in Rust.

2 min read Original article ↗

CI codecov

A fast Markdown linter written in Rust. Compatible with CommonMark and GitHub Flavored Markdown (GFM).

Usage

mado check .
mado check path/to/*.md

Performance

Approx. 49-60x faster than existing linters (e.g. markdownlint).

---
config:
    xyChart:
        height: 200
        titleFontSize: 14
        chartOrientation: horizontal
        xAxis:
            labelFontSize: 12
            titleFontSize: 14
        yAxis:
            labelFontSize: 12
            titleFontSize: 14
---
xychart-beta
    title "Linting ~1,500 Markdown files (Lower is faster)"
    x-axis ["mado (rust)", "markdownlint-cli (node.js)", "markdownlint (ruby)", "markdownlint-cli2 (node.js)"]
    y-axis "Time (seconds)" 0 --> 10
    bar [0.129, 6.381, 6.609, 7.817]
Loading

This benchmark was conducted on a MacBook Pro (2021, M1 Max) using hyperfine with GitLab documentation as the dataset.

Installation

Homebrew (macOS and Linux)

brew tap akiomik/mado https://github.com/akiomik/mado.git
brew install mado

Nix (macOS and Linux)

nix profile install github:akiomik/mado

Arch Linux (Linux)

Scoop (Windows)

scoop install https://raw.githubusercontent.com/akiomik/mado/refs/heads/main/pkg/scoop/mado.json

WinGet (Windows)

# For security reasons, installing from local manifest files requires that this feature be enabled by an administrator.
# For more details, see https://learn.microsoft.com/en-us/windows/package-manager/winget/install#local-install
winget settings --enable LocalManifestFiles

curl.exe -o mado.yml https://raw.githubusercontent.com/akiomik/mado/refs/heads/main/pkg/winget/mado.yml
winget install -m mado.yml

Manually

Pre-built binaries are available for download from the release page.

Supported Rules

Mado supports most markdownlint rules.

  • ✅ Stable support
  • 🔨 Unstable support
  • ⚠️ Unsupported option(s)
  • ❌ Not supported
Rule Support Note
MD001 ✅
MD002 ✅
MD003 🔨
MD004 ✅
MD005 ✅
MD006 ✅
MD007 🔨
MD009 ✅
MD010 ✅
MD012 ✅
MD013 ✅
MD014 ✅
MD018 ✅
MD019 ✅
MD020 🔨
MD021 ✅
MD022 ✅
MD023 ✅
MD024 ✅
MD025 ✅
MD026 ✅
MD027 🔨
MD028 ✅
MD029 ✅
MD030 ✅
MD031 ✅
MD032 🔨
MD033 ✅
MD034 ✅
MD035 ✅
MD036 ✅
MD037 ✅
MD038 ✅
MD039 ✅
MD040 ✅
MD041 ✅
MD046 ✅
MD047 ✅

Configuration

Mado can be configured via mado.toml or .mado.toml file in the current directory. You can also use global configuration files located in:

  • Linux: ~/.config/mado/mado.toml
  • macOS: ~/.config/mado/mado.toml
  • Windows: ~\AppData\Roaming\mado\mado.toml

For more details, see the example mado.toml and the JSON Schema for mado.toml.

GitHub Actions

Mado is compatible with GitHub Actions.

# Basic usage (runs `mado check .`)
- uses: akiomik/mado@v0.3.0

# Custom usage (runs `mado` with specified arguments)
- uses: akiomik/mado@v0.3.0
  with:
    args: '--config path/to/mado.toml check path/to/*.md'

Development

just is required.

Running Tests

Linting Code

Benchmarking

# Download Markdown dataset
./scripts/benchmarks/setup.sh

# Benchmark mado, mdl and markdownlint-cli using hyperfine
./scripts/benchmarks/comparison.sh

Profiling

First, install flamegraph:

Then run:

Fuzz Testing

First, install cargo-fuzz:

Then run: