Biblioteca
KatanA Markdown Model
Biblioteca Rust que convierte Markdown en un modelo documental con nodos y posiciones de origen. Trata la estructura documental independientemente del renderizado.
Desarrolladores Rust que trabajan con estructura Markdown, nodos y source span
01
Funciones implementadas
02
Primeros pasos
- Añada katana-markdown-model a su proyecto Rust.
- Pase la entrada mediante MarkdownInput y entregue el modelo resultante de parse a la siguiente etapa.
cargo add katana-markdown-modelPrepare 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.
Fuentesuse 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 común de Markdown para las etapas posteriores
Convierta Markdown en KmmDocument y KmmNode independientes del renderer y entregue la misma estructura al viewer, linter o análisis propio. KmmNodeKind distingue headings, párrafos, enlaces, imágenes, fórmulas, tablas, code blocks y alertas.
Resolver de nuevo los targets de metadata tras editar
Cuando cambian las posiciones o IDs, use byte range, line/column, fingerprint y context anterior/posterior de metadata para resolver candidatos en el documento nuevo. El resultado distingue resolución, movimiento, conflicto y falta de resolución para anotaciones o información externa.
02 / KMM
Flujo de entrada a salida
Crear MarkdownInput
Pase path y texto a MarkdownInput::from_content. La entrada puede proceder de un archivo o de una cadena en memoria; el consumidor decide cómo tratar el source antes de parsear.
Hacer parse a KmmDocument
KatanaMarkdownModel::parse devuelve Result<KmmDocument, KmmError>. El document correcto contiene path, fingerprint y nodes de nivel superior; cada node contiene kind, source y children.
Usar AST o el resultado de reconcile
Normalmente entregue nodes y source span al viewer/linter; para actualizar metadata, pase old document, new document y metadata a reconcile. El resultado incluye metadata actualizada y la resolución de cada target.
03 / KMM
APIs y CLI principales
KatanaMarkdownModel::parse — Análisis de Markdown- Analiza MarkdownInput y devuelve KmmDocument. Los errores de parse se devuelven como KmmError para que el consumidor trate la entrada inválida.
KmmNodeKind — Tipos de nodos- Representa como enum Heading, Paragraph, Text, Link, Image, InlineMath, DollarMathBlock, List, CodeBlock, Table y Alert. La siguiente etapa decide el kind sin volver a parsear para un renderer concreto.
MetadataTarget — Destinos de metadatos- Conserva como target de metadata file path, node ID, byte range, line-column range, text fingerprint y context anterior/posterior. No depende de un único número de línea.
TargetResolutionKind — Estados de resolución- Clasifica el resultado como Resolved, Moved, Conflict o Unresolved. Devuelve el node movido, candidatos múltiples y razones para que el consumidor separe la adopción automática de la revisión humana.
04 / KMM
Entender con un ejemplo
Leer el AST y las posiciones originales
Analice Markdown con un encabezado y un párrafo mediante MarkdownInput::from_content y lea kind y source span de cada nodo de nivel superior, en lugar de un resultado renderizado. Esto permite vincular una selección o análisis con el texto original; recorra children para lo anidado y pase documentos antiguo/nuevo con metadata a reconcile después de editar.
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
Integración y límites
Conservar el límite renderer-neutral
KMM proporciona un modelo documental renderer-neutral y no depende de un viewer o editor concreto. No lleve el render ni la sincronización UI a KMM; el consumidor transforma el AST según su responsabilidad.
Respetar el alcance inicial de KMM
El alcance inicial ofrece source range, line-column, raw snippet, fingerprint y resolución posterior de MetadataTarget. Integre solo con node y metadata API de KMM, sin referenciar directamente implementaciones de KDV o KatanA.
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.