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

APIs for document snapshots, export data, and diagnostics

Evidence

Connecting Markdown structure with diagram rendering from KRR

Evidence

Exporting to HTML, PDF, PNG, and JPEG

Evidence

02

Getting started

  1. Get the repository and check the README for runtime and font requirements.
  2. 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.

Evidence
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

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

  1. 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.

  2. 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.

  3. 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.

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

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.

RepositoryREADME99371a97dbc5
Evidence · KDV
All products