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

Detecção de violações por Markdown lint

Fontes

Auxílio de correção com fix

Fontes

Formatação com fmt e integração de editor por LSP

Fontes

02

Primeiros passos

  1. Instale a CLI com Cargo e entre no projeto que deseja verificar.
  2. 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.

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

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

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

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

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

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

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.

RepositórioLeia-me1e1da206977a
Fontes · KML
Todos os produtos