Base e ferramentas
KatanA Markdown Linter
Biblioteca Rust e CLI kml para verificar regras Markdown, aplicar correções seguras e formatar. Também oferece integração de editor por LSP e servidor MCP opcional.
Desenvolvedores e equipes que mantêm especificações Markdown e README
01
Funções implementadas
02
Primeiros passos
- Instale a CLI com Cargo e entre no projeto que deseja verificar.
- Execute kml check README.md para revisar os apontamentos; ao corrigir, confira o diff enquanto usa fix ou fmt.
Prepare Rust e as ferramentas de desenvolvimento necessárias e consulte o README indicado para os requisitos antes da integração. Os exemplos são pontos de entrada e não garantem funcionamento em todos os ambientes.
Fontescargo install katana-markdown-linter
kml check README.md
kml fix --diff README.md01 / KML
Casos de uso
Verificar a qualidade do Markdown no CI
kml check verifica um arquivo, glob, stdin ou os Markdown do diretório atual e produz diagnósticos com rule ID, severity e posição. Violação resulta em exit 1; erro de filesystem/configuração, em exit 2, permitindo ligar a saída ao gate do CI.
Automatizar safe fix e formatação
kml fix ou check --fix aplica correções safe, enquanto kml fmt organiza quebras de linha, linhas vazias e indentação de listas. Correções unsafe podem exigir opt-in explícito, separando CI e trabalho local.
02 / KML
Fluxo da entrada à saída
Passar content e options
Na library, passe a string Markdown e LintOptions a MarkdownLinter::lint; na CLI, indique kml check README.md ou --stdin. Resolva config e regras conforme a rota de execução.
Avaliar todas as rules
O linter cria um severity map a partir de options e aplica as rules de Markdown ao path, content e configuração. Os resultados viram LintResult público, com rule ID e severity para o consumidor.
Tratar diagnóstico ou resultado da correção
lint retorna Vec<LintResult>; fix aplica resultados corrigíveis por até 8 pass e retorna FixResult. Na CLI, o exit code informa ao CI se restam violações antes ou depois da correção.
03 / KML
APIs e CLI principais
MarkdownLinter::lint — Análise de Markdown- Faz lint de content em memória e retorna Result<Vec<LintResult>, Error>. É adequado para testes de integração e conexão com editor quando o chamador quer controlar o I/O de arquivos.
MarkdownLinter::fix — Correção segura- Copia content e aplica safe fix até não haver diagnóstico corrigível ou até atingir 8 pass. O content, a quantidade aplicada e os detalhes do retorno permitem conferir a mudança.
MarkdownLinter::fix_with_results — Correção de diagnósticos existentes- É a entrada de baixo nível que aplica safe fix a LintResult já obtido. Use-a quando quiser mostrar os diagnósticos e depois entregar o mesmo resultado ao processo de correção.
kml check / fix / fmt — Comandos CLI- A CLI oferece check, fix, fmt, stdin, file, glob e saída JSON. O consumidor pode deixar a descoberta de arquivos para a CLI ou controlar content e options diretamente pela library API.
04 / KML
Entenda com um exemplo
Detectar violação de nível de título com a API Rust
Passe # Title e depois ### Skipped heading a MarkdownLinter::lint com as opções padrão e mostre o rule ID e message de cada LintResult. É o caso público de incremento de nível e demonstra diagnósticos sem alterar o texto.
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
Integração e limites
Separar responsabilidades safe/unsafe
fix normal e check --fix ficam limitados a safe fix; unsafe fix exige --unsafe --yes explícitos. No CI use a rota safe; para reescrita intencional do desenvolvedor, use a rota unsafe.
Ligar exit code ao quality gate
Sem arquivo, a CLI percorre recursivamente o diretório atual; violação é exit 1 e erro de filesystem/configuração é exit 2. O CI pode usar o exit code como decisão primária, sem depender do texto do diagnóstico.
Fontes
Apresentação baseada nos repositórios públicos disponíveis no momento da pesquisa. A implementação e os passos podem ser conferidos no commit fixado do link.