01
已实现功能
02
开始使用
- 准备 Rust 和 README 中列出的 runtime asset,并安装 krr CLI。
- 准备 Mermaid 输入文件,使用 render 命令生成 SVG。
请准备 Rust 和必要的开发工具,并在导入前通过链接的 README 确认环境要求。示例命令是功能入口,不保证在所有环境中运行。
依据cargo install katana-render-runtime-cli
printf 'graph TD\n A-->B\n' > sample.mmd
krr mermaid render --input sample.mmd --output sample.svg01 / KRR
使用场景
在同一合约中将图表和公式转换为 SVG
将 Mermaid、ZenUML、Draw.io、PlantUML 的图表源码和 MathJax 的 TeX 作为带种类的 RenderInput 传入。KRR 选择对应 runtime,返回包含 SVG、尺寸、viewBox、runtime 信息、警告与错误及缓存指纹的 RenderOutput,因此预览或文档显示端无需分别实现各类图表的渲染。
公式输入的诊断预览
MathJaxRenderer 将普通行内 TeX 和 display 数式转换为 SVG;TeX 无效或 runtime 缺失时会保留输入字符串,并在 diagnostics.errors 中返回原因。这适合在编辑界面展示原文和诊断,而不让一次渲染失败导致整个界面失败。公开测试分别验证正常输入的 SVG 与尺寸,以及异常输入的原文、0 尺寸和非空错误。
02 / KRR
从输入到输出的流程
输入来源和类型
调用者通过 RenderKind、分类源、RenderConfig、RenderPolicy 和 RenderContext 设置 RenderInput。 KRR 不接受 Markdown AST,并负责直接处理图表或 TeX 字符串。
解决运行时和主题
RuntimePathResolver 优先考虑指定的运行时路径,如果未指定,它将解析 Mermaid、Draw.io、MathJax 中的捆绑资源以及 PlantUML 中的版本化缓存路径。 PlantUML读取vendor_config中的主题和缓存目录,如果设置无效则返回RenderError。
接收 SVG 和诊断
Renderer::render的返回值是RenderOutput。返回正常图表和公式的 SVG 和正尺寸,并返回 RenderError 或后端定义的原始源以及输入错误或运行时缺失的诊断,允许用户查看和记录警告和错误。
03 / KRR
主要 API 与 CLI
Renderer::render — 渲染契约- 统一的入口是Renderer::render(&RenderInput)。如果RenderKind和source的组合与后端不匹配,则会是UnsupportedKind,如果运行时解析失败,则会是RuntimeResolution等RenderError。
RenderOutput — 输出数据- RenderOutput 包含 svg、width、height、view_box、runtime、profile、diagnostics 和 cache_fingerprint。除了 SVG 字符串,调用方还能取得显示尺寸和判断结果能否复用所需的元数据。
krr render — 命令行入口- CLI 以 krr mermaid render、krr drawio render、krr plantuml render 的形式处理输入文件。 --output、--runtime以及PlantUML的--theme、--theme-mode、--cache-dir都可以指定,如果省略输出文件,则结果将输出到标准输出。
比较/诊断命令- reference-update、compare 和 bench 以 fixture directory 为目标。compare 的默认 minimum score 是 99.0,因此可以作为产品集成时的回归检查导线,但这只是质量比较机制,并不是执行性能保证。
04 / KRR
通过示例理解
通过诊断处理 MathJax 中的无效输入
在 Rust 中通过 RuntimePathResolver 解析 MathJax runtime,再把 RenderInput 传给 MathJaxRenderer。对于输入 \not_a_real_mathjax_command,render 仍返回结果,其中 svg 为原文,width 和 height 为 0,diagnostics.errors 非空。正常的 E = mc^2 则产生 SVG、viewBox 和正的宽高。
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
集成条件与职责边界
介绍的先决条件
公开 workspace 使用 Rust 1.95.0 和 edition 2024,runtime asset 管理 Mermaid、Draw.io、MathJax、PlantUML 等的版本和 checksum。可使用默认 asset,也可通过显式 path 或环境变量替换 runtime。
责任边界
KRR 负责分类图形和 TeX 源的运行时绘制。我们不负责 Markdown AST 分析、HTML/PDF/PNG/JPG 文档导出、查看器/编辑器 UI、KDV 分页和文档导出,因此这些都合并在上层模型/查看器/应用程序端。
依据
内容基于调查时点的公开代码仓库。可通过链接中的固定提交确认实现和使用方法。