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
Aider aux corrections avec fix
RéférencesFormater avec fmt et intégrer les éditeurs via LSP
Références02
Premiers pas
- Installez la CLI avec Cargo et placez-vous dans le projet à inspecter.
- 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érencescargo install katana-markdown-linter
kml check README.md
kml fix --diff README.md01 / 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
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.
É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.
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.
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.