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

Markdown-Lint-Verstöße erkennen

Belege

Korrekturen mit fix unterstützen

Belege

Mit fmt formatieren und über LSP in Editoren integrieren

Belege

02

Erste Schritte

  1. Installieren Sie die CLI mit Cargo und wechseln Sie in das zu prüfende Projekt.
  2. 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.

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

01 / 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

  1. Ü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.

  2. 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.

  3. 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.

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

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.

Code-RepositoryREADME-Dokument1e1da206977a
Belege · KML
Alle Produkte