01
已實作功能
02
開始使用
- 透過 Cargo 安裝 CLI,並進入要檢查的專案。
- 執行 kml check README.md 查看問題;確認差異後再使用 fix 或 fmt。
請準備 Rust 與必要的開發工具,並在導入前透過連結的 README 確認環境需求。執行範例是功能入口,不保證在所有環境中運作。
依據cargo install katana-markdown-linter
kml check README.md
kml fix --diff README.md01 / KML
使用情境
使用 CI 檢查 Markdown 質量
kml check 檢查單個檔案、glob、stdin 或當前目錄下的 Markdown,並獲取包含規則 ID、嚴重性和位置的診斷資訊。發生違規時退出1,發生檔案系統/配置錯誤時退出2,因此可以連線CI成功/失敗判斷。
自動安全修復和整形
使用 kml fix 或 check --fix 應用安全修復,並使用 kml fmt 安排換行符、空行和列表縮排等佈局。不安全的修改可以僅限於明確的選擇加入,從而將 CI 和開發人員的本地責任分開。
02 / KML
從輸入到輸出的流程
傳遞內容和選項
對於庫,將 Markdown 字串和 LintOptions 傳遞給 MarkdownLinter::lint,對於 CLI,使用 kml check README.md 或 --stdin 指定輸入源。配置和規則設定根據使用的執行路徑進行解析。
評估所有規則
linter 根據 options 建立 severity map,並將 Markdown rules 應用於 target path、content 和 rule settings。結果轉換為公開的 LintResult,呼叫方可以讀取 rule ID 和 severity。
處理診斷或糾正結果
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 測試的輸入相同,會產生標題級別跳躍的診斷。
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不依賴於診斷文本的表示法,可以使用退出程式碼作為初步判斷。
依據
內容根據調查時點的公開儲存庫。可透過連結中的固定提交確認實作與使用方式。