Base e strumenti
KatanA Markdown Linter
Libreria Rust e CLI kml per controllare le regole Markdown, applicare correzioni sicure e formattare. Offre anche integrazione editor tramite LSP e un server MCP opzionale.
Sviluppatori e team che mantengono specifiche Markdown e README
01
Funzioni implementate
02
Per iniziare
- Installa la CLI con Cargo e spostati nel progetto da controllare.
- Esegui kml check README.md per esaminare gli avvisi; quando correggi, controlla il diff mentre usi fix o fmt.
Prepara Rust e gli strumenti di sviluppo necessari e consulta il README collegato per i requisiti prima dell'integrazione. Gli esempi sono punti di partenza e non garantiscono il funzionamento in ogni ambiente.
Fonticargo install katana-markdown-linter
kml check README.md
kml fix --diff README.md01 / KML
Casi d'uso
Controllare la qualità Markdown in CI
Con kml check puoi controllare un file, glob, stdin o il current directory del Markdown e ottenere diagnostica con rule ID, severity e posizione. Una violazione produce exit 1, mentre un errore filesystem/config produce exit 2: è collegabile alla decisione CI.
Automatizzare safe fix e formattazione
kml fix o check --fix applicano correzioni safe, mentre kml fmt sistema interruzioni di riga, righe vuote e indentazione delle liste. Le correzioni unsafe richiedono opt-in esplicito, separando responsabilità di CI e ambiente locale.
02 / KML
Flusso da input a output
Passare content e options
Con la library passa la stringa Markdown e LintOptions a MarkdownLinter::lint; con la CLI specifica la sorgente con kml check README.md o --stdin. Config e regole vengono risolte in base al percorso di esecuzione.
Valutare tutte le rule
Il linter costruisce la severity map dalle options e applica il gruppo di Markdown rule a path, content e configurazione. Il risultato viene convertito in LintResult pubblico, leggibile tramite rule ID e severity.
Gestire diagnostica o risultato di fix
lint restituisce Vec<LintResult>; fix applica risultati correggibili fino a un massimo di 8 pass e restituisce FixResult. La CLI comunica con exit code se restano violazioni o se restano dopo la correzione.
03 / KML
API e CLI principali
MarkdownLinter::lint — Analisi di Markdown- Esegue lint sul content in memoria e restituisce Result<Vec<LintResult>, Error>. È adatto a test d’integrazione e collegamenti editor in cui il chiamante deve controllare direttamente il file I/O.
MarkdownLinter::fix — Correzione sicura- Copia internamente content e applica safe fix finché non restano diagnostiche correggibili o raggiunge 8 pass. Da content, numero di applicazioni e dettagli puoi verificare il risultato della modifica.
MarkdownLinter::fix_with_results — Correzione delle diagnostiche esistenti- Entry point di basso livello che applica safe fix a LintResult già ottenuti. Usalo quando hai mostrato la diagnostica e vuoi passare gli stessi risultati al processo di correzione.
kml check / fix / fmt — Comandi CLI- La CLI offre check, fix, fmt, stdin, file, glob e output JSON. Puoi lasciare la ricerca dei file alla CLI oppure gestire direttamente content e options con la library API.
04 / KML
Capire con un esempio
Rilevare una violazione del livello degli heading con l’API Rust
Passa MarkdownLinter::lint il Markdown con # Title seguito da ### Skipped heading e stampa rule ID e message di ogni LintResult. È lo stesso input del test pubblico sull’incremento del livello degli heading e mostra la violazione come diagnostica.
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
Integrazione e limiti
Separare responsabilità safe/unsafe
fix normale e check --fix sono limitati a safe fix; unsafe fix richiede esplicitamente --unsafe --yes. In CI usa il percorso safe, mentre le riscritture intenzionali dello sviluppatore seguono il percorso unsafe.
Collegare exit code al quality gate
Senza file specificato viene elaborato ricorsivamente il current directory; una violazione dà exit 1 e un errore filesystem/config dà exit 2. La CI può usare exit code come decisione primaria senza dipendere dal testo della diagnostica.
Fonti
Presentazione basata sui repository pubblici disponibili al momento della ricerca. Implementazione e procedure sono verificabili nel commit fissato del link.