Base / outil

KatanA Markdown Linter

Une bibliothèque Rust et une CLI kml pour le lint Markdown, les corrections automatiques sûres et le formatage, avec intégration éditeur par LSP et serveur MCP optionnel.

Développeurs et équipes qui maintiennent des spécifications Markdown et des README

01

Capacités implémentées

Formater avec fmt et intégrer les éditeurs via LSP

Références

02

Premiers pas

  1. Installez la CLI avec Cargo et placez-vous dans le projet à inspecter.
  2. Lancez kml check README.md pour examiner les diagnostics ; utilisez fix ou fmt après vérification du diff.

Préparez Rust et les outils de développement nécessaires, puis consultez le README lié pour les prérequis avant l'installation. Les exemples indiquent un point de départ et ne garantissent pas le fonctionnement dans tous les environnements.

Références
sh
cargo install katana-markdown-linter
kml check README.md
kml fix --diff README.md

01 / KML

Cas d'utilisation

Contrôler la qualité Markdown en CI

kml check inspecte un fichier, un glob, stdin ou les Markdown sous le répertoire courant et renvoie des diagnostics avec rule ID, severity et position. Une violation renvoie exit 1 ; une erreur filesystem/config renvoie exit 2.

Automatiser les corrections sûres et le formatage

Utilisez kml fix ou check --fix pour appliquer les corrections safe, et kml fmt pour les fins de ligne, lignes vides et retraits de listes. Les corrections unsafe restent un opt-in explicite, séparant CI et réécriture locale.

02 / KML

Flux entrée-sortie

  1. Fournir contenu et options

    Dans la library, passez le contenu Markdown et LintOptions à MarkdownLinter::lint ; dans la CLI, choisissez kml check README.md, --stdin ou une autre source. La configuration et les rules sont résolues selon le chemin choisi.

  2. Évaluer toutes les rules

    Le linter construit une severity map depuis options, applique les rules au path, au content et à la configuration, puis renvoie des LintResult publics contenant rule ID et severity.

  3. Traiter diagnostics ou corrections

    lint renvoie Vec<LintResult>. fix applique les résultats corrigeables à une copie pendant au plus 8 pass et renvoie FixResult ; la CLI indique par exit code les violations restantes, y compris après correction.

03 / KML

API et CLI principales

MarkdownLinter::lint — Analyse de Markdown
Analyse le content en mémoire et renvoie Result<Vec<LintResult>, Error>, laissant l'I/O fichier à l'appelant ; cette entrée convient aux tests et à l'éditeur.
MarkdownLinter::fix — Correction sûre
Copie le contenu et applique les corrections safe jusqu'à disparition des résultats corrigeables ou 8 pass. FixResult expose content réécrit, nombre et détails des corrections.
MarkdownLinter::fix_with_results — Correction des diagnostics existants
Applique des corrections safe à une tranche de LintResult déjà obtenue, après affichage ou inspection des diagnostics.
kml check / fix / fmt — Commandes CLI
La CLI offre check, fix, fmt, stdin, file, glob et sortie JSON. L'appelant peut laisser la CLI découvrir les fichiers ou gérer directement content et options via la library.

04 / KML

Comprendre par un exemple

Détecter une violation de niveau de titre avec l'API Rust

Le code passe # Title puis ### Skipped heading à MarkdownLinter::lint avec les options par défaut et affiche le rule ID et le message de chaque LintResult. Cette entrée reproduit le cas public d'incrément de niveau de titre et montre que le linter renvoie des diagnostics plutôt que de modifier le texte.

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

Intégration et limites

Séparer safe et unsafe

fix et check --fix restent safe ; une correction unsafe exige explicitement --unsafe --yes. Utilisez le chemin safe en CI et réservez l'autre à une réécriture volontaire.

Utiliser les exit codes comme gate

Sans fichier, la CLI parcourt récursivement les Markdown du répertoire courant ; violation = exit 1, erreur filesystem/config = exit 2. La CI peut utiliser ces statuts sans dépendre du texte des diagnostics.

Références

Cette présentation repose sur les dépôts publics au moment de l'examen. Vérifiez l'implémentation et l'utilisation dans les commits figés liés.

DépôtFichier README1e1da206977a
Références · KML
Tous les produits