Library
KatanA Render Runtime
A Rust library and CLI that convert diagram and TeX math sources to SVG, with shared input/output APIs for results and diagnostics.
Rust developers embedding SVG rendering for diagrams and math
01
Implemented capabilities
02
Getting started
- Prepare Rust and the runtime assets described in the README, then install the krr CLI.
- Prepare a Mermaid input file and generate SVG with the render command.
Prepare Rust and the required development tools, then check the linked README for environment requirements before installing. Examples show an entry point and do not guarantee operation in every environment.
Evidencecargo install katana-render-runtime-cli
printf 'graph TD\n A-->B\n' > sample.mmd
krr mermaid render --input sample.mmd --output sample.svg01 / KRR
Where it fits
One SVG contract for diagrams and math
Pass Mermaid, ZenUML, Draw.io, PlantUML, or MathJax TeX as a typed RenderInput. KRR returns SVG, dimensions, viewBox, runtime information, warnings/errors, and a cache fingerprint in RenderOutput, so preview or document viewers need not implement each diagram kind themselves.
Diagnostic-aware math preview
MathJaxRenderer converts ordinary inline TeX and display math to SVG, while invalid TeX or a missing runtime keeps the input string and returns the reason in diagnostics.errors. Public tests verify SVG and dimensions for valid input and the original input, zero dimensions, and a non-empty error list for invalid input, allowing an editor to show the source and reason instead of failing the whole screen.
02 / KRR
Input to output
Provide typed source
Set RenderKind, the already-classified source string, RenderConfig, RenderPolicy, and RenderContext in RenderInput. KRR consumes diagram or TeX text directly; parsing a Markdown AST remains outside this renderer boundary.
Resolve runtime and theme
RuntimePathResolver prefers an explicitly supplied runtime path. When it is omitted, it resolves bundled Mermaid, Draw.io, or MathJax assets or a versioned PlantUML cache path; PlantUML also reads theme and cache-directory settings from vendor_config and reports invalid configuration as RenderError.
Receive SVG and diagnostics
Renderer::render returns RenderOutput for successful diagrams and math, including SVG and positive dimensions. Input errors or missing runtimes can return RenderError, while a backend may instead return the raw source with diagnostics, allowing callers to display and record warnings and errors.
03 / KRR
Key APIs and CLI
Renderer::render- The common entry point is Renderer::render(&RenderInput). A RenderKind/source combination unsupported by the backend produces UnsupportedKind, while runtime resolution failures are reported as errors such as RuntimeResolution.
RenderOutput- Returns svg, width, height, view_box, runtime, profile, diagnostics, and cache_fingerprint. The contract therefore carries display dimensions and reuse metadata in addition to the SVG string.
krr render- The CLI processes input files with krr mermaid render, krr drawio render, and krr plantuml render. It supports --output and --runtime, PlantUML-specific --theme, --theme-mode, and --cache-dir, and writes the result to standard output when no output file is supplied.
compare and bench- reference-update, compare, and bench operate on fixture directories. compare defaults to a 99.0 minimum score, which provides a regression-check path for integration but is a quality comparison mechanism rather than a guarantee of runtime performance.
04 / KRR
Concrete example
Handle invalid MathJax with diagnostics
Resolve a MathJax runtime with RuntimePathResolver, pass RenderInput containing \not_a_real_mathjax_command to MathJaxRenderer, and inspect the returned raw source and diagnostics. The render call still returns output with the original source, width and height of zero, and non-empty diagnostics.errors; valid E = mc^2 input instead returns SVG, viewBox, and positive dimensions.
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
Integration boundaries
Prepare Rust and runtime assets
The published workspace requires Rust 1.95.0 and edition 2024, and its runtime assets for Mermaid, Draw.io, MathJax, and PlantUML are versioned and checksummed. Choose the bundled asset or replace it with an explicit path or environment-controlled runtime as the deployment requires.
Keep document responsibilities outside KRR
KRR is responsible for runtime rendering of already-classified diagram and TeX source. Parsing a Markdown AST, HTML/PDF/PNG/JPG document export, viewer/editor UI, KDV pagination, and document export remain responsibilities of the model, viewer, or application layer that composes KRR.
Evidence
This overview is based on the public repositories at the time of review. Verify implementation and usage in the linked pinned commits.