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
02
Per iniziare
- Aggiungi katana-markdown-model al progetto Rust.
- Passa l'input con MarkdownInput e inoltra il modello risultante dal parse alla fase successiva.
cargo add katana-markdown-modelPrepara 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.
Fontiuse 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
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.
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.
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.
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.