Libreria
KatanA Render Runtime
Libreria Rust e CLI che convertono sorgenti di diagrammi e formule TeX in SVG. Un'API comune restituisce risultato di rendering e diagnostica.
Sviluppatori Rust che integrano rendering SVG di diagrammi e formule
01
Funzioni implementate
02
Per iniziare
- Prepara Rust e gli asset runtime indicati nel README e installa la CLI krr.
- Prepara un file Mermaid e genera SVG con il comando render.
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.
Fonticargo install katana-render-runtime-cli
printf 'graph TD\n A-->B\n' > sample.mmd
krr mermaid render --input sample.mmd --output sample.svg01 / KRR
Casi d'uso
Convertire diagrammi e formule in SVG con lo stesso contratto
Passa sorgenti Mermaid, ZenUML, Draw.io e PlantUML e TeX di MathJax come RenderInput tipizzati. KRR sceglie il runtime e restituisce RenderOutput con SVG, dimensioni, viewBox, informazioni sul runtime, warning/errori e cache fingerprint; preview e document viewer non devono implementare ogni tipo di diagramma.
Preview diagnostica per input matematici
MathJaxRenderer converte TeX inline e display in SVG e, con TeX non valido o runtime non installato, conserva la stringa di input e restituisce il motivo in diagnostics.errors. È adatto a mostrare sorgente e diagnostica nell’editor senza far fallire l’intera schermata. I test pubblici verificano SVG e dimensioni nel caso valido, input originale, dimensioni 0 ed errori non vuoti nel caso anomalo.
02 / KRR
Flusso da input a output
Inserire sorgente e tipo
Il chiamante configura in RenderInput RenderKind, source classificato, RenderConfig, RenderPolicy e RenderContext. KRR non riceve un Markdown AST: è responsabile di elaborare direttamente la stringa del diagramma o del TeX.
Risolvere runtime e tema
RuntimePathResolver dà priorità al runtime path esplicito; se manca, risolve gli asset bundled di Mermaid, Draw.io e MathJax e il versioned cache path di PlantUML. Per PlantUML legge theme e cache directory da vendor_config e restituisce RenderError se la configurazione non è valida.
Ricevere SVG e diagnostica
Renderer::render restituisce RenderOutput. Per diagrammi e formule validi produce SVG e dimensioni positive; con input errato o runtime assente restituisce RenderError oppure raw source e diagnostics definiti dal backend, così il chiamante può mostrare e registrare warning ed errori.
03 / KRR
API e CLI principali
Renderer::render — Contratto di rendering- L’entry point unificato è Renderer::render(&RenderInput). Se RenderKind e source non sono compatibili con il backend si ottiene UnsupportedKind; un errore nella risoluzione del runtime produce errori RenderError come RuntimeResolution.
RenderOutput — Dati di uscita- L’output contiene svg, width, height, view_box, runtime, profile, diagnostics e cache_fingerprint. Non ricevi solo la stringa SVG, ma anche dimensioni e metadati necessari per decidere il riuso.
krr render — Ingresso CLI- La CLI elabora file con krr mermaid render, krr drawio render e krr plantuml render. Puoi specificare --output, --runtime e, per PlantUML, --theme, --theme-mode e --cache-dir; senza file di output il risultato va su stdout.
Comandi per confronto e diagnostica- reference-update, compare e bench lavorano su una fixture directory. Il minimum score predefinito di compare è 99.0: può servire alla regressione d’integrazione, ma è un meccanismo di confronto qualitativo e non una garanzia delle prestazioni di esecuzione.
04 / KRR
Capire con un esempio
Gestire input MathJax non valido con diagnostica
Sul lato Rust risolvi il runtime MathJax con RuntimePathResolver e passa un RenderInput a MathJaxRenderer. Con input \not_a_real_mathjax_command, render restituisce comunque un output: svg contiene l’input originale, width e height sono 0 e diagnostics.errors non è vuoto. Con E = mc^2 valido ottieni SVG, viewBox e larghezza e altezza positive.
use katana_render_runtime::{
MathJaxRenderer, RenderConfig, RenderContext, RenderInput, RenderKind,
RenderPolicy, Renderer, RuntimePathResolver,
};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let runtime = RuntimePathResolver::resolve(RenderKind::MathJax, None)?;
let renderer = MathJaxRenderer::with_runtime_path(runtime);
let input = RenderInput {
kind: RenderKind::MathJax,
source: r"\not_a_real_mathjax_command".to_string(),
config: RenderConfig::default(),
policy: RenderPolicy::default(),
context: RenderContext::default(),
};
let output = renderer.render(&input)?;
println!("svg={} errors={:?}", output.svg, output.diagnostics.errors);
Ok(())
}05 / KRR
Integrazione e limiti
Prerequisiti di adozione
Il workspace pubblico usa Rust 1.95.0 ed edition 2024; gli asset runtime di Mermaid, Draw.io, MathJax e PlantUML sono gestiti con version e checksum. Puoi usare gli asset predefiniti oppure sostituire il runtime con path espliciti o variabili d’ambiente.
Confine di responsabilità
KRR esegue il rendering runtime di sorgenti di diagrammi e TeX classificati. Non analizza Markdown AST, non esporta documenti in HTML/PDF/PNG/JPG, non gestisce viewer/editor UI né pagination ed export documentale di KDV: queste responsabilità appartengono a modello, viewer e app superiori.
Fonti
Presentazione basata sui repository pubblici disponibili al momento della ricerca. Implementazione e procedure sono verificabili nel commit fissato del link.