Library
KatanA Document Viewer
A Rust library for embedding document previews and HTML, PDF, and image export into an app. It uses document data independent of a UI framework.
Rust developers embedding document viewers or HTML, PDF, and image export
01
Implemented capabilities
02
Getting started
- Get the repository and check the README for runtime and font requirements.
- Use the export_debug example with a Markdown file and output directory, then inspect the generated document.
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.
Evidencegit 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-output01 / KDV
Where it fits
A shared foundation for viewing and export
Use KDV when an app needs to keep Markdown independent of application UI while representing it as document frames, state, and diagnostics. The same render pipeline can then serve HTML, PDF, PNG, and JPEG export, with viewing and export sharing a common boundary.
Preparing documents with diagrams
KDV can build Markdown containing diagrams or math and delegate diagram rendering to KRR while retaining unsupported semantics as diagnostics and raw source. This leaves input that the viewer cannot interpret available for downstream handling instead of silently discarding it.
02 / KDV
Input to output
Normalize the input
Read the input file and normalize CRLF and CR to LF, then normalize Markdown fences with MarkdownFenceNormalizer. Build a source containing the URI, source kind, revision, and document content before parsing.
Build a snapshot and graph
Parse the Markdown with KatanaMarkdownModel::parse and create a snapshot with DocumentSnapshotFactory::from_kmm. Put that snapshot together with a Markdown export profile and theme in BuildRequest, then call ForgePipeline::build to produce a BuildGraph that includes diagnostics.
Export artifacts and diagnostics
Pass the BuildGraph to ForgePipeline::export to create a format-specific artifact, then persist the build graph, coverage matrix, summary TOML, and exported files together. The public export example rejects empty artifact bytes so callers do not receive an incomplete result.
03 / KDV
Key APIs and CLI
DocumentSnapshotFactory- Combines KMM's document with DocumentSource to create the DocumentSnapshot consumed by viewer and forge code. The snapshot depends on the source content as well as its URI and revision, not on the body alone.
ForgePipeline::build- Consumes a BuildRequest containing the snapshot, BuildProfile, and theme, then returns a BuildGraph containing the document snapshot, profile, forge diagnostics, and rendered diagrams.
ForgePipeline::export- Consumes an ExportRequest containing the build graph, format, and theme, then returns ExportOutput for HTML, PDF, PNG, or JPEG. The result combines the artifact with forge diagnostics for the next stage.
KRR diagram backend- Passing DiagramRenderingBackend with KrrDiagramRenderEngine into the pipeline connects diagram rendering to KRR's boundary. This API does not make KDV own application UI or a separate diagram implementation.
04 / KDV
Concrete example
Build README and inspect the document node count
This code reads README.md, normalizes CRLF/CR and Markdown fences, parses it, creates a snapshot, and builds a BuildGraph with the Markdown export profile before printing the node count. It is the build portion extracted from the public export_debug example, so it does not save files or export the four formats; run export_debug separately when file output is needed.
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
Integration boundaries
Keep the UI backend outside KDV
KDV does not depend on egui or eframe and does not expose KUC types in its public API. A higher-level application such as KatanA coordinates viewer/editor synchronization, while KDV stays responsible for the document, viewer, and export boundaries.
Treat the public release as scaffolding
The public README describes the release as scaffolding, and v0.1.0 is a UI-independent artifact, forge, and export foundation. Integrators must not fill KMM parser gaps by reparsing or treat KRR-unsupported semantics as completed features; those remain explicit adoption boundaries.
Evidence
This overview is based on the public repositories at the time of review. Verify implementation and usage in the linked pinned commits.