Base y herramientas
KatanA Markdown Linter
Biblioteca Rust y CLI kml para comprobar reglas Markdown, aplicar correcciones seguras y formatear. También ofrece integración de editor mediante LSP y un servidor MCP opcional.
Desarrolladores y equipos que mantienen especificaciones Markdown y README
01
Funciones implementadas
02
Primeros pasos
- Instale la CLI con Cargo y vaya al proyecto que quiere comprobar.
- Ejecute kml check README.md para revisar las observaciones; si corrige, revise el diff mientras usa fix o fmt.
Prepare Rust y las herramientas de desarrollo necesarias y consulte el README enlazado para conocer los requisitos antes de integrar. Los ejemplos son puntos de entrada y no garantizan el funcionamiento en todos los entornos.
Fuentescargo install katana-markdown-linter
kml check README.md
kml fix --diff README.md01 / KML
Casos de uso
Inspeccionar la calidad Markdown en CI
kml check inspecciona un archivo, glob, stdin o Markdown bajo current directory y devuelve diagnósticos con rule ID, severity y posición. Exit 1 indica infracciones y exit 2 filesystem/config error, por lo que puede conectarse a CI.
Automatizar safe fix y formato
Use kml fix o check --fix para aplicar correcciones safe y kml fmt para ajustar saltos de línea, líneas vacías e indentación de listas. Las correcciones unsafe requieren opt-in explícito, separando CI y trabajo local.
02 / KML
Flujo de entrada a salida
Pasar content y options
En la library entregue la cadena Markdown y LintOptions a MarkdownLinter::lint; en la CLI use kml check README.md o --stdin para elegir el origen. Resuelva config y rules según la ruta ejecutada.
Evaluar todas las rules
El linter construye un severity map desde options y aplica las reglas Markdown al target path, content y rule config. Convierte el resultado en LintResult público, con rule ID y severity legibles para el consumidor.
Tratar diagnóstico o resultado de fix
lint devuelve Vec<LintResult>; fix aplica resultados corregibles durante como máximo 8 pass y devuelve FixResult. La CLI comunica por exit code si quedan infracciones antes o después de corregir.
03 / KML
APIs y CLI principales
MarkdownLinter::lint — Análisis de Markdown- Inspecciona content en memoria y devuelve Result<Vec<LintResult>, Error>. Es adecuado para tests de integración o editores que quieren controlar el file I/O desde el consumidor.
MarkdownLinter::fix — Corrección segura- Copia content internamente y aplica safe fix hasta que no queden diagnósticos corregibles o llegue a 8 pass. Devuelve content, número de aplicaciones y detalles del cambio.
MarkdownLinter::fix_with_results — Corrección de diagnósticos existentes- Es la entrada de bajo nivel que aplica safe fix a LintResult ya obtenidos; úsela cuando primero muestra diagnósticos y después pasa esos mismos resultados al proceso de corrección.
kml check / fix / fmt — Comandos CLI- La CLI ofrece check, fix, fmt, stdin, file, glob y salida JSON. Puede delegar la búsqueda de archivos a la CLI o controlar content y options directamente con la library API.
04 / KML
Entender con un ejemplo
Detectar una infracción de nivel de encabezado
Pase a MarkdownLinter::lint un Markdown con # Title seguido de ### Skipped heading e imprima el rule ID y message de cada LintResult. La entrada coincide con la prueba pública de una infracción del incremento de encabezados.
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
Integración y límites
Separar safe y unsafe
El fix normal y check --fix se limitan a safe fix; unsafe fix requiere --unsafe --yes explícito. Use la ruta safe en CI y la unsafe solo para una reescritura intencionada del desarrollador.
Conectar exit code al quality gate
Sin file especificado se procesa recursivamente current directory; una infracción produce exit 1 y filesystem/config error produce exit 2. CI puede usar exit code como decisión primaria, sin depender del texto del diagnóstico.
Fuentes
Presentación basada en los repositorios públicos disponibles en el momento de la investigación. La implementación y los pasos se pueden comprobar en el commit fijado del enlace.