Basis / Tool
KatanA Markdown Linter
Eine Rust-Bibliothek und kml-CLI für Markdown-Linting, sichere automatische Korrekturen und Formatierung, mit Editorintegration über LSP und optionalem MCP-Server.
Entwickler und Teams, die Markdown-Spezifikationen und READMEs pflegen
01
Implementierte Fähigkeiten
02
Erste Schritte
- Installieren Sie die CLI mit Cargo und wechseln Sie in das zu prüfende Projekt.
- Führen Sie kml check README.md aus und prüfen Sie die Diagnosen; verwenden Sie fix oder fmt erst nach Prüfung des Diffs.
Bereiten Sie Rust und die erforderlichen Entwicklungstools vor und prüfen Sie vor der Installation die Umgebungsanforderungen im verknüpften README. Beispiele zeigen einen Einstieg und garantieren keinen Betrieb in jeder Umgebung.
Belegecargo install katana-markdown-linter
kml check README.md
kml fix --diff README.md01 / KML
Anwendungsfälle
Überprüfen Sie die Markdown-Qualität mit CI
kml check prüft Markdown aus einer einzelnen Datei, einem Glob, stdin oder dem current directory und liefert Diagnosen mit rule ID, severity und Position. Bei Verstößen ist der exit code 1, bei filesystem/config error 2; damit lässt sich die CI-Auswertung verbinden.
Automatisieren Sie sicheres Fixieren und Formen
Wenden Sie sichere Fixes mit kml fix an oder aktivieren Sie --fix und ordnen Sie Layouts wie Zeilenumbrüche, Leerzeilen und Listeneinrückungen mit kml fmt an. Unsichere Änderungen können auf explizite Opt-Ins beschränkt werden, wodurch die lokalen Verantwortlichkeiten von CI und Entwickler getrennt werden.
02 / KML
Ablauf von Eingabe zu Ausgabe
Übergeben Sie Inhalte und Optionen
Übergeben Sie für die Bibliothek die Markdown-Zeichenfolge und LintOptions an MarkdownLinter::lint. Geben Sie für die CLI die Eingabequelle mit kml check README.md oder --stdin an. Konfigurations- und Regeleinstellungen werden entsprechend dem verwendeten Ausführungspfad aufgelöst.
Bewerten Sie alle Regeln
Der Linter erstellt aus options eine severity map und wendet die Markdown-Regeln auf target path, content und rule settings an. Das Ergebnis wird in öffentliche LintResult-Werte konvertiert, deren rule ID und severity die Nutzung auswerten kann.
Behandeln Sie Diagnose- oder Korrekturergebnisse
lint gibt Vec<LintResult> zurück, fix wendet korrigierbare Ergebnisse bis zu 8 Durchgänge an und gibt ein FixResult zurück. In der CLI wird der Exit-Code verwendet, um das CI darüber zu informieren, ob der Verstoß bestehen bleibt oder ob der Verstoß auch nach der Korrektur bestehen bleibt.
03 / KML
Wichtige APIs und CLI
MarkdownLinter::lint — Markdown-Prüfung- Lint den content im Speicher und gibt Result<Vec<LintResult>, Error> zurück. Dies eignet sich für Integrationstests und Editor-Zusammenarbeit, bei denen der Aufrufer Datei-I/O steuern möchte.
MarkdownLinter::fix — Sichere Korrektur- Kopiert den content intern und wendet safe fixes an, bis keine reparierbaren Diagnosen mehr vorhanden sind oder 8 Durchläufe erreicht sind. Der Rückgabewert enthält content, die Anzahl der Anwendungen und Details zur Prüfung des Ergebnisses.
MarkdownLinter::fix_with_results — Korrektur vorhandener Befunde- Ein Einstiegspunkt auf niedriger Ebene, um eine sichere Korrektur auf ein bereits erhaltenes LintResult anzuwenden. Wird verwendet, um Diagnosen anzuzeigen und die gleichen Ergebnisse dann an einen Korrekturprozess weiterzuleiten.
kml check /fix /fmt- CLI bietet Prüf-, Korrektur-, FMT-, STDIN-, Datei-, Glob-, JSON-Ausgabe usw. Benutzer können die Dateiexploration der CLI überlassen oder Inhalte und Optionen direkt mit der Bibliotheks-API verwalten.
04 / KML
An einem Beispiel verstehen
Erkennen von Verstößen auf Überschriftenebene mit der Rust-API
Übergeben Sie Markdown mit # Title und anschließendem ### Skipped heading an MarkdownLinter::lint und zeigen Sie rule ID und message jedes zurückgegebenen LintResult an. Wie im Test des öffentlichen Crates erscheint die Verletzung des Überschrifteninkrements als Diagnose.
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
Integration und Grenzen
Trennen Sie sichere/unsichere Verantwortlichkeiten
Reguläre Fixes und check --fix sind auf sichere Fixes beschränkt, und unsichere Fixes werden explizit mit --unsafe --yes angegeben. Der Betrieb kann in sichere Routen bei automatischem CI und unsichere Routen bei absichtlichem Umschreiben durch den Entwickler unterteilt werden.
Exit-Code mit Quality Gate verbinden
Wenn keine Datei angegeben ist, wird die rekursive Verarbeitung unterhalb des aktuellen Verzeichnisses durchgeführt, Exit 1 wird bei Verstößen und Exit 2 bei Dateisystem-/Konfigurationsfehlern ausgegeben. CI ist nicht von der Notation des Diagnosetextes abhängig und kann den Exit-Code als primäre Beurteilung verwenden.
Belege
Diese Übersicht basiert auf den öffentlichen Repositories zum Zeitpunkt der Prüfung. Implementierung und Nutzung können in den verknüpften fixierten Commits geprüft werden.