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

Detección de infracciones mediante Markdown lint

Fuentes

Asistencia de corrección con fix

Fuentes

Formateo con fmt e integración de editor mediante LSP

Fuentes

02

Primeros pasos

  1. Instale la CLI con Cargo y vaya al proyecto que quiere comprobar.
  2. 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.

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

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

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

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

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

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

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.

RepositorioLéame1e1da206977a
Fuentes · KML
Todos los productos