Libreria

KatanA Markdown Model

Libreria Rust che converte Markdown in un modello documentale con nodi e posizioni sorgente. Gestisce la struttura documentale indipendentemente dal rendering.

Sviluppatori Rust che lavorano con struttura Markdown, nodi e source span

01

Funzioni implementate

Creazione di un modello documentale da Markdown

Fonti

Conservazione delle posizioni sorgente tramite ID dei nodi e source span

Fonti

Verifica dei riferimenti ai metadati esterni tra documenti prima e dopo la modifica

Fonti

02

Per iniziare

  1. Aggiungi katana-markdown-model al progetto Rust.
  2. Passa l'input con MarkdownInput e inoltra il modello risultante dal parse alla fase successiva.
sh
cargo add katana-markdown-model

Prepara Rust e gli strumenti di sviluppo necessari e consulta il README collegato per i requisiti prima dell'integrazione. Gli esempi sono punti di partenza e non garantiscono il funzionamento in ogni ambiente.

Fonti
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

Casi d'uso

AST comune per le fasi successive

Converte Markdown in KmmDocument e KmmNode renderer-neutral per passare la stessa struttura a viewer, linter e analisi personalizzate. Heading, paragraph, link, image, formula, tabella, code block e alert sono distinguibili tramite KmmNodeKind.

Risolvere di nuovo i target metadata dopo l’editing

Quando posizione o ID del nodo cambiano, usa byte range, line/column, fingerprint e context precedente/successivo del metadata salvato per cercare il candidato nel nuovo documento. Il risultato distingue resolved, moved, conflict e unresolved, utile per seguire annotazioni e informazioni esterne.

02 / KMM

Flusso da input a output

  1. Creare MarkdownInput

    Passa path e contenuto a MarkdownInput::from_content. L’input può provenire da un file o da una stringa in memoria; prima del parse il chiamante decide come gestire source.

  2. Eseguire il parse in KmmDocument

    KatanaMarkdownModel::parse restituisce Result<KmmDocument, KmmError>. Il document riuscito contiene path, fingerprint e nodes di primo livello; ogni node contiene kind, source e children.

  3. Usare AST o risultato reconcile

    Normalmente passa nodes e source span a viewer/linter; per aggiornare metadata passa old document, new document e metadata a reconcile. Il risultato comprende metadata aggiornati e resolution di ogni target.

03 / KMM

API e CLI principali

KatanaMarkdownModel::parse — Analisi di Markdown
Analizza MarkdownInput e restituisce KmmDocument. Un parse fallito torna al chiamante come KmmError, così l’integrazione può gestire l’errore di input.
KmmNodeKind — Tipi di nodi
Rappresenta come enum elementi strutturati quali Heading, Paragraph, Text, Link, Image, InlineMath, DollarMathBlock, List, CodeBlock, Table e Alert. Le fasi successive possono riconoscere kind senza un reparse specifico del renderer.
MetadataTarget — Target dei metadati
Conserva per il target metadata file path, node ID, byte range, intervallo line-column, text fingerprint e context precedente/successivo. È un input per la nuova risoluzione che non dipende da un solo numero di riga.
TargetResolutionKind — Stati di risoluzione
Classifica il risultato in Resolved, Moved, Conflict e Unresolved. Restituendo node spostati, più candidati e motivazioni, permette al chiamante di separare adozione automatica e verifica umana.

04 / KMM

Capire con un esempio

Leggere AST e posizioni nella sorgente

Analizza un Markdown con heading e paragraph e leggi kind e source span di ogni nodo di primo livello. È un punto d’ingresso per collegare selezione visuale o risultato dell’analisi al testo originale tramite posizione, non tramite output di rendering.

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

Integrazione e limiti

Mantenere il confine renderer-neutral

KMM fornisce un modello documentale renderer-neutral e non dipende da viewer o editor specifici. Non portare rendering o sincronizzazione UI nel KMM: il chiamante trasforma l’AST KMM secondo la propria responsabilità.

Assumere lo scope iniziale di KMM

Lo scope iniziale espone source range, line-column, raw snippet, fingerprint e nuova risoluzione dei metadata target. Non fare riferimento direttamente all’implementazione KDV o KatanA: integra usando solo node e metadata API pubbliche di KMM.

Fonti

Presentazione basata sui repository pubblici disponibili al momento della ricerca. Implementazione e procedure sono verificabili nel commit fissato del link.

Archivio del codiceLeggimi9a7f647ab097
Fonti · KMM
Tutti i prodotti