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
02
Primeiros passos
- Adicione katana-markdown-model ao projeto Rust.
- Passe a entrada por MarkdownInput e entregue o modelo resultante de parse à etapa seguinte.
cargo add katana-markdown-modelPrepare 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.
Fontesuse 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
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.
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.
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.
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.