基礎與工具

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 或當前目錄下的 Markdown,並獲取包含規則 ID、嚴重性和位置的診斷資訊。發生違規時退出1,發生檔案系統/配置錯誤時退出2,因此可以連線CI成功/失敗判斷。

自動安全修復和整形

使用 kml fix 或 check --fix 應用安全修復,並使用 kml fmt 安排換行符、空行和列表縮排等佈局。不安全的修改可以僅限於明確的選擇加入,從而將 CI 和開發人員的本地責任分開。

02 / KML

從輸入到輸出的流程

  1. 傳遞內容和選項

    對於庫,將 Markdown 字串和 LintOptions 傳遞給 MarkdownLinter::lint,對於 CLI,使用 kml check README.md 或 --stdin 指定輸入源。配置和規則設定根據使用的執行路徑進行解析。

  2. 評估所有規則

    linter 根據 options 建立 severity map,並將 Markdown rules 應用於 target path、content 和 rule settings。結果轉換為公開的 LintResult,呼叫方可以讀取 rule ID 和 severity。

  3. 處理診斷或糾正結果

    lint 返回 Vec<LintResult>,fix 應用最多 8 次可修復結果並返回 FixResult。在 CLI 中,退出程式碼用於通知 CI 違規是否仍然存在,或者即使在糾正後違規是否仍然存在。

03 / KML

主要 API 與 CLI

MarkdownLinter::lint — Markdown檢查
MarkdownLinter::lint 對記憶體中的 content 執行檢查並返回 Result<Vec<LintResult>, Error>。它適用於由呼叫方控制檔案 I/O 的整合測試和 editor 整合。
MarkdownLinter::fix — 安全修復
MarkdownLinter::fix 複製 content 並應用 safe fix,直到沒有可修復的診斷或達到 8 個 pass。您可以從返回值的 content、applied count 和 details 檢視變更結果。
MarkdownLinter::fix_with_results — 修復既有診斷
一個低階入口點,用於對已獲得的 LintResult 應用安全修復。用於顯示診斷結果,然後將相同的結果傳遞給糾正過程。
kml check / fix / fmt — 命令列
CLI 提供檢查、修復、fmt、stdin、檔案、glob、JSON 輸出等。使用者可以將檔案探索留給 CLI,或直接使用庫 API 管理內容和選項。

04 / KML

透過範例理解

使用 Rust API 檢測標題級別違規

把依次包含 # Title 和 ### Skipped heading 的 Markdown 傳給 MarkdownLinter::lint,並列印每個 LintResult 的 rule ID 和 message。這與公開 crate 測試的輸入相同,會產生標題級別跳躍的診斷。

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

整合條件與責任邊界

獨立的安全/不安全責任

常規修復和 check --fix 僅限於安全修復,不安全修復則通過 --unsafe --yes 明確指定。操作可分為自動CI中的安全路線和開發人員故意重寫的情況下的不安全路線。

將退出程式碼連線到質量門

如果未指定檔案,則將在當前目錄下執行遞迴處理,對於違規將發出 exit 1,對於檔案系統/配置錯誤將發出 exit 2。 CI不依賴於診斷文本的表示法,可以使用退出程式碼作為初步判斷。

依據

內容根據調查時點的公開儲存庫。可透過連結中的固定提交確認實作與使用方式。

儲存庫閱讀指南1e1da206977a
依據 · KML
所有產品