Markdown linter は、project が大きくなってから本格的に必要になる tool です。README や設計 memo が数本だけなら、heading level、空行、list indent、line width の問題は review で見つけられます。しかし repository に数百、数千の Markdown file が増えると、lint は CI、pre-commit、document publish flow に入ります。その段階では、speed と configurability が developer experience に直結します。

今日紹介する akiomik/mado は、Rust 製の Markdown linter です。目的は明確で、CommonMark と GitHub Flavored Markdown に対応しながら、markdownlint style の rule check を提供し、大きな document repository でも頻繁に走らせやすい速度を目指しています。

公開時点の GitHub page では、約 377 stars、10 forks。主な言語は Rust、license は Apache-2.0 です。Repository は 2024-12-16 に作成され、最近の push は 2026-06-15 です。Release page では最新 version が v0.3.0、GitHub 上の公開日は 2025-04-11 です。

プロジェクト概要

項目内容
Repositoryakiomik/mado
位置づけRust Markdown linter
Stars約 377
Forks10
主な言語Rust
LicenseApache-2.0
Latest versionv0.3.0

まず「十分に速い」を解く

Mado の README で一番目立つ訴求は performance です。Project が示している benchmark は GitLab documentation を dataset とし、約 1,500 個の Markdown file を lint して、hyperfine で mado、Ruby 版 markdownlint、Node ecosystem の markdownlint-cli と markdownlint-cli2 を比較しています。

この結果は「project 自身の benchmark」として読むべきで、すべての repository で同じ数字が出るとは限りません。それでも、ここには現実的な痛点があります。Markdown lint は遅すぎると避けられます。Document repository が大きくなるほど、lint は CI、pre-push hook、local check に入りやすくなります。毎回長く待たされるなら、team は実行頻度を下げるか、publish 直前にまとめて format issue を直すようになります。

Rust implementation の価値はそこにあります。Mado は Markdown parsing、rule traversal、file scanning を低遅延の CLI としてまとめ、たまに実行する hygiene check ではなく、頻繁に走らせる tool にしようとしています。

markdownlint に近い rule model

Mado は多くの markdownlint rules を support しています。README の rule table では、それぞれの rule が stable、unstable、unsupported option、not supported として示されています。Heading level、trailing spaces、blank lines、line length、list indent、code block language、final newline など、よく使う rule は広く cover されています。

これは重要です。Markdown lint の難しさは、単に format を検出することではなく、team の既存 rules をどう移すかにあります。多くの project は MD001、MD013、MD024 のような markdownlint rule number に慣れています。新しい tool が完全に別の naming と config model を持っていると、migration cost は上がります。

Mado はすべての markdownlint behavior を完全に cover すると主張していません。現在の support level を明示しているので、むしろ慎重に採用しやすいです。まず新しい repository で使う、または既存 repository の重要 rules だけを合わせ、差分を見てから置き換えを判断できます。

config と install path が揃っている

Mado の基本 usage は直接的です。

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

Config file は current directory の mado.toml または .mado.toml に置けます。User-level config directory も使えます。README には example config と JSON Schema への link もあり、editor completion、config review、repository template に役立ちます。

Install path も複数あります。

  1. macOS / Linux では Homebrew または Nix。
  2. Arch Linux では pacman -S mado。
  3. Windows では Scoop または WinGet manifest。
  4. Package manager を使わない場合は、release page から pre-built binary を入手できます。

CLI tool としては、この広さは実用的です。「cargo install だけ」だと、documentation team、platform engineering team、CI image のどれもが Rust build を受け入れる必要があります。Pre-built package と一般的な package manager は導入時の摩擦を下げます。

GitHub Actions support は文書 repository に向く

Mado は GitHub Actions の使い方も提供しています。

- uses: akiomik/mado@v0.3.0

Custom argument が必要な場合は、args で config や check path を指定できます。たとえば特定の document directory だけを確認したり、明示的に mado.toml を渡したりできます。

この設計により、Mado は local CLI に留まりません。多くの document quality issue は PR stage で見つけるべきものです。Heading jump、list indent の不一致、language のない code block、長すぎる line、final newline の欠落。これらを CI に入れれば、reviewer は機械的な format ではなく、content の正確さに集中できます。

v0.3.0 は tags と shell completion を追加

Latest release の v0.3.0 では、tags と shell completion が主な update として入っています。Comrak などの dependency も更新されました。Breaking change として、comrak が 0.36.0 から 0.38.0 に上がっています。

User 目線では shell completion は地味ですが便利な CLI detail です。Maintainer 目線では Markdown parser dependency を追い続けることも重要です。Markdown linter の correctness は、CommonMark と GFM を parser がどう扱うかに強く依存します。Parser が古いままだと、rule layer が整っていても実際の document ecosystem からずれていきます。

Mado はまだ比較的若い project です。Release pace と rule coverage は今後も見る必要があります。ただ、README、install channel、GitHub Actions、schema、benchmark、fuzz testing などを見る限り、作者は一度きりの command ではなく、maintainable な toolchain として育てようとしています。

向いている場面

Mado が特に向いているのは、次のような project です。

  1. Markdown file が多く、既存 lint が CI や local run で遅く感じる。
  2. markdownlint style の rules は保ちつつ、より速い implementation を試したい。
  3. macOS、Linux、Windows で同じ CLI を導入したい。
  4. Markdown lint を human review だけでなく GitHub Actions に明示的に入れたい。
  5. Rust toolchain に抵抗がなく、成長中の linter を段階的に試せる。

すべての team に必要な tool ではありません。Project が markdownlint の特殊 option や custom rule ecosystem に強く依存しているなら、すぐ置き換えるのは得策ではないかもしれません。まず独立した document directory や新規 repository で試し、rule difference と false positive を見てから migration scope を決めるのが現実的です。

まとめ

akiomik/mado は、positioning がはっきりした Markdown lint tool です。Rust で速い check を提供し、markdownlint の馴染みある rule model を使い、config、install、GitHub Actions、schema などの engineering detail も補っています。

Repository の Markdown が増え、lint が待ち時間になっているなら、Mado は候補に入れる価値があります。Document rule を再発明する tool ではなく、既存の Markdown standard を local と CI で高頻度に実行しやすくする tool です。