基盤・ツール

KatanA Markdown Linter

Markdownの規約検査、安全な自動修正、整形を行うRustライブラリとkml CLIです。LSPによるエディタ連携と任意のMCPサーバーも備えます。

Markdown仕様書やREADMEを継続的に整える開発者・チーム

01

実装済みの機能

Markdown lintによる規約違反の検出

根拠

fixによる修正支援

根拠

fmtによる整形とLSPによるエディタ連携

根拠

02

はじめ方

  1. CargoでCLIを導入し、検査したいプロジェクトへ移動します。
  2. kml check README.mdで指摘を確認します。修正する場合は差分を確認しながらfixやfmtを利用します。

Rustと必要な開発ツールを準備し、導入前にリンク先のREADMEで環境要件を確認してください。実行例は機能の入口であり、すべての環境での動作を保証するものではありません。

根拠
sh
cargo install katana-markdown-linter
kml check README.md
kml fix --diff README.md

01 / KML

どんな場面で使うか

CIでMarkdown品質を検査

kml checkで単一ファイル、glob、stdin、またはcurrent directory以下のMarkdownを検査し、rule ID・severity・位置付きの診断を得ます。違反時exit 1、filesystem/config error時exit 2なのでCIの成否判定へ接続できます。

safe fixと整形を自動化

kml fixまたはcheck --fixでsafeな修正を適用し、kml fmtで改行・空行・リスト字下げなどのレイアウトを整えます。unsafeな修正は明示opt-inに限定できるため、CIと開発者ローカルの責務を分けられます。

02 / KML

入力から出力までの流れ

  1. contentとoptionsを渡す

    libraryならMarkdown文字列とLintOptionsをMarkdownLinter::lintへ渡し、CLIならkml check README.mdや--stdinなどで入力源を指定します。configとrule設定は利用する実行経路に合わせて解決されます。

  2. 全ruleを評価する

    linterはoptionsからseverity mapを作り、Markdown rule群を対象path・content・rule設定へ適用します。結果は公開LintResultへ変換され、rule IDやseverityを利用側が読めます。

  3. 診断または修正結果を扱う

    lintはVec<LintResult>を返し、fixは最大8 passまでfix可能な結果を適用してFixResultを返します。CLIでは違反が残るか、修正後も違反が残るかをexit codeでCIへ伝えます。

03 / KML

主要API・CLIの使い分け

MarkdownLinter::lint
メモリ上のcontentをlintし、Result<Vec<LintResult>, Error>を返します。ファイルI/Oを呼び出し側で制御したい統合テストやeditor連携に向きます。
MarkdownLinter::fix
contentを内部コピーし、fix可能な診断がなくなるか8 passに達するまでsafe fixを適用します。戻り値のcontent、適用数、詳細から変更結果を確認できます。
MarkdownLinter::fix_with_results
既に取得したLintResultへsafe fixを適用する低レベル入口です。診断を表示した後に同じ結果を修正処理へ渡す場合に使います。
kml check / fix / fmt
CLIはcheck、fix、fmt、stdin、file、glob、JSON出力などを提供します。利用者はファイル探索をCLIへ任せるか、library APIでcontentとoptionsを直接管理できます。

04 / KML

具体例で理解する

見出しレベル違反をRust APIで検出

# Titleの次に### Skipped headingを置いたMarkdownをMarkdownLinter::lintへ渡し、返った各LintResultのrule IDとmessageを表示します。公開crateのテストと同じく、見出しincrement違反が診断として現れる入力です。

rust
use katana_markdown_linter::{LintOptions, MarkdownLinter};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let results = MarkdownLinter::lint(
        "# Title\n\n### Skipped heading\n",
        &LintOptions::default(),
    )?;
    for result in results {
        println!("{}: {}", result.rule_id, result.message);
    }
    Ok(())
}

05 / KML

組み込み条件と責務の境界

safe/unsafeの責務を分ける

通常のfixとcheck --fixはsafe fixに限定し、unsafe fixは--unsafe --yesを明示指定します。自動CIではsafe経路、開発者の意図的な書換えではunsafe経路という運用に分けられます。

exit codeを品質gateへ接続する

ファイル未指定ならcurrent directory以下を再帰処理し、違反はexit 1、filesystem/config errorはexit 2です。CIは診断本文の表記に依存せず、exit codeを一次判定にできます。

根拠

調査時点の公開リポジトリに基づく紹介です。リンク先の固定コミットで実装と手順を確認できます。

リポジトリREADME1e1da206977a
根拠 · KML
すべての製品