Biblioteca

KatanA Markdown Model

Biblioteca Rust que converte Markdown em um modelo documental com nós e posições de origem. Trata a estrutura documental independentemente da renderização.

Desenvolvedores Rust que trabalham com estrutura Markdown, nós e source span

01

Funções implementadas

Construção de modelo documental a partir de Markdown

Fontes

Preservação da posição de origem por IDs de nós e source span

Fontes

Verificação de referências de metadados externos entre documentos antes e depois da edição

Fontes

02

Primeiros passos

  1. Adicione katana-markdown-model ao projeto Rust.
  2. Passe a entrada por MarkdownInput e entregue o modelo resultante de parse à etapa seguinte.
sh
cargo add katana-markdown-model

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
rust
use katana_markdown_model::{KatanaMarkdownModel, MarkdownInput};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let document = KatanaMarkdownModel::parse(
        MarkdownInput::from_content("README.md", "# Title\n\nBody\n"),
    )?;
    println!("{document:?}");
    Ok(())
}

01 / KMM

Casos de uso

AST comum para o processamento posterior de Markdown

Converte Markdown em KmmDocument e KmmNode renderer-neutral para compartilhar a mesma estrutura com viewer, linter e análise própria. Headings, parágrafos, links, imagens, fórmulas, tabelas, code block e alert são distinguidos por KmmNodeKind.

Resolver metadata target depois da edição

Quando a posição ou o ID de um node muda, use byte range, line/column, fingerprint e context anterior e posterior para encontrar candidatos no novo documento. O resultado distingue Resolved, Moved, Conflict e Unresolved, permitindo acompanhar anotações e dados externos.

02 / KMM

Fluxo da entrada à saída

  1. Criar MarkdownInput

    Passe path e corpo a MarkdownInput::from_content. A entrada pode vir de um arquivo ou de uma string em memória; o consumidor decide como tratar o source antes do parse.

  2. Fazer o parse em KmmDocument

    KatanaMarkdownModel::parse retorna Result<KmmDocument, KmmError>. O document bem-sucedido contém path, fingerprint e nodes de nível superior; cada node possui kind, source e children.

  3. Usar o AST ou o resultado de reconcile

    Normalmente, passe nodes e source span ao viewer/linter. Para atualizar metadata, passe old document, new document e metadata a reconcile; o resultado contém metadata atualizada e a resolution de cada target.

03 / KMM

APIs e CLI principais

KatanaMarkdownModel::parse — Análise de Markdown
É a entrada básica que analisa MarkdownInput e retorna KmmDocument. Falhas de parse retornam KmmError ao chamador, que pode tratar o erro de entrada.
KmmNodeKind — Tipos de nós
Representa como enum elementos Heading, Paragraph, Text, Link, Image, InlineMath, DollarMathBlock, List, CodeBlock, Table e Alert. As etapas seguintes podem verificar kind sem fazer reparse específico do renderer.
MetadataTarget — Alvos de metadados
Mantém file path, node ID, byte range, line-column range, text fingerprint e context anterior e posterior. É uma entrada de re-resolução que não depende de um único número de linha.
TargetResolutionKind — Estados de resolução
Separa os resultados em Resolved, Moved, Conflict e Unresolved. Como pode devolver node movido, múltiplos candidatos e o motivo, o consumidor decide entre adoção automática e revisão humana.

04 / KMM

Entenda com um exemplo

Ler o AST e as posições da fonte

O código analisa Markdown com heading e parágrafo e percorre os nodes de nível superior para ler kind e source span. Ele produz um modelo documental, não HTML nem uma visualização; essas posições ligam uma seleção ou análise ao texto original.

rust
use katana_markdown_model::{KatanaMarkdownModel, MarkdownInput};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let document = KatanaMarkdownModel::parse(MarkdownInput::from_content(
        "README.md",
        "# Title\n\nBody\n",
    ))?;
    for node in &document.nodes {
        println!("kind={:?} source={:?}", node.kind, node.source);
    }
    Ok(())
}

05 / KMM

Integração e limites

Preservar a fronteira renderer-neutral

KMM fornece um modelo documental renderer-neutral e não depende de viewer ou editor específico. Não leve renderização ou sincronização de UI para KMM; o consumidor transforma o AST KMM dentro da própria responsabilidade.

Respeitar o escopo inicial do KMM

O escopo inicial oferece source range, line-column, raw snippet, fingerprint e re-resolução de metadata target. Integre apenas com as APIs públicas de node e metadata do KMM, sem referenciar diretamente implementações do KDV ou KatanA.

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-me9a7f647ab097
Fontes · KMM
Todos os produtos