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

Construcción de un modelo documental desde Markdown

Fuentes

Conservación de posiciones de origen mediante IDs de nodo y source span

Fuentes

Comprobación de referencias de metadatos externos entre documentos antes y después de editar

Fuentes

02

Primeros pasos

  1. Añada katana-markdown-model a su proyecto Rust.
  2. Pase la entrada mediante MarkdownInput y entregue el modelo resultante de parse a la siguiente etapa.
sh
cargo add katana-markdown-model

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

Fuentes
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 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

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

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

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

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

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.

RepositorioLéame9a7f647ab097
Fuentes · KMM
Todos los productos