库

KatanA Document Viewer

将文档预览以及 HTML、PDF、图像输出集成到应用中的 Rust 库,处理不依赖 UI 框架的文档数据。

将文档 viewer 及 HTML、PDF、图像输出集成到应用中的 Rust 开发者

01

已实现功能

处理文档 snapshot、输出 artifact 和 diagnostic 信息的 API

依据

连接 Markdown 文档结构与 KRR 图表渲染的流程

依据

导出 HTML、PDF、PNG、JPEG

依据

02

开始使用

  1. 获取代码仓库,并通过 README 确认运行环境和字体要求。
  2. 使用 export_debug 示例指定 Markdown 文件和输出位置,确认生成的文档。

请准备 Rust 和必要的开发工具,并在导入前通过链接的 README 确认环境要求。示例命令是功能入口,不保证在所有环境中运行。

依据
sh
git clone https://github.com/HiroyukiFuruno/katana-document-viewer.git
cd katana-document-viewer
cargo run -p katana-document-viewer --example export_debug -- README.md ./export-output

01 / KDV

使用场景

显示和导出文档的通用平台

当您想要将 Markdown 视为 KDV 文档框架、状态和诊断而不直接将其绑定到特定于应用程序的 UI,并且想要从同一渲染管道生成 HTML、PDF、PNG 和 JPEG 时,它非常适合。查看器显示和导出处理边界可以共享。

准备导出包含图形和表格的文档

您可以使用 KDV 构建包含图表和公式的 Markdown,将图表渲染委托给 KRR,并保留不支持的含义作为诊断和原始来源。当您希望将无法在显示端解释的输入保留为稍后可以处理的状态,而不是默默地丢弃它时,这是基础。

02 / KDV

从输入到输出的流程

  1. 标准化输入

    读取输入文件,把 CRLF/CR 统一为 LF,并用 MarkdownFenceNormalizer 规范化 Markdown fence。为输入 source 设置 URI、source kind、revision 和正文。

  2. 创建 snapshot 和 build graph

    用 KatanaMarkdownModel::parse 解析 Markdown,再用 DocumentSnapshotFactory::from_kmm 创建 snapshot。将 markdown export profile 和 theme 传给 BuildRequest,通过 ForgePipeline::build 生成包含诊断信息的 BuildGraph。

  3. 保存工件和诊断

    将构建图传递给 ForgePipeline::export 来为每种格式创建工件,并将它们与构建图、覆盖率和摘要 TOML 一起输出。如果工件为空,则示例导出过程将导致错误,并且用户将不会收到不完整的工件。

03 / KDV

主要 API 与 CLI

DocumentSnapshotFactory — 文档快照
组合 KMM 文档和 DocumentSource 以创建查看器/forge 将处理的 DocumentSnapshot。快照的先决条件不仅是输入正文,还有 URI 和修订版。
ForgePipeline::build — 构建流水线
处理 BuildRequest 的快照、BuildProfile 和主题,并返回包含文档快照、配置文件、诊断和渲染图表的 BuildGraph。
ForgePipeline::export — 文档导出
从 ExportRequest 的构建图、格式和主题返回 ExportOutput。格式为 HTML、PDF、PNG 和 JPEG,工件和forge diagnostics可以组合并传递到下一阶段。
KRR diagram backend — 图表后端
通过将DiagramRenderingBackend 和KrrDiagramRenderEngine 传递到管道,将图表渲染器连接到KRR 边界。 KDV 本身并不是一个直接拥有应用程序 UI 或其他图表实现的 API。

04 / KDV

通过示例理解

构建README并检查文档节点数的示例

此代码读取 README.md,对其进行规范化、解析和快照,创建带有 markdown 导出配置文件的 BuildGraph,并显示节点数。构建部分是从公开export_debug示例中提取的,它不会保存到文件或导出为4种格式。

rust
use katana_document_viewer::{
    BuildProfile, BuildRequest, DiagramRenderingBackend, DocumentSnapshotFactory,
    DocumentSource, ForgePipeline, KrrDiagramRenderEngine, MarkdownFenceNormalizer,
    SourceKind, SourceRevision, SourceUri,
};
use katana_markdown_model::{KatanaMarkdownModel, MarkdownInput};
use std::fs;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = "README.md";
    let content = MarkdownFenceNormalizer::normalize(&fs::read_to_string(path)?);
    let source = DocumentSource {
        uri: SourceUri(format!("file://{path}")),
        kind: SourceKind::Markdown,
        revision: SourceRevision("local".to_string()),
        content: content.clone(),
    };
    let document = KatanaMarkdownModel::parse(MarkdownInput::from_content(path, content))?;
    let snapshot = DocumentSnapshotFactory::from_kmm(source, document);
    let request = BuildRequest {
        snapshot,
        profile: BuildProfile::markdown_export(),
        theme: Default::default(),
    };
    let pipeline = ForgePipeline::new(DiagramRenderingBackend::new(KrrDiagramRenderEngine));
    let graph = pipeline.build(&request)?;
    println!("nodes={}", graph.snapshot.document.nodes.len());
    Ok(())
}

05 / KDV

集成条件与职责边界

不要引入 UI 后端

KDV 不依赖于 egui/eframe 等 UI 后端,也不向公开 API 公开 KUC 类型。 KatanA 等更高级别的应用程序负责同步查看器和编辑器,而 KDV 则专注于文档/查看器/导出边界。

作为脚手架引入

公开 README 的状态为 Scaffolding,v0.1.0 是独立于 UI 的 artifact/forge/export 基础。集成时不能用重新解析来掩盖 KMM parser 的缺口,也不能把 KRR 尚不支持的语义当成已完成的能力。

依据

内容基于调查时点的公开代码仓库。可通过链接中的固定提交确认实现和使用方法。

代码仓库阅读指南99371a97dbc5
依据 · KDV
全部产品