ライブラリ

KatanA Document Viewer

文書のプレビューとHTML・PDF・画像への出力をアプリに組み込むRustライブラリです。UIのフレームワークに依存しない文書データを扱います。

文書viewerやHTML・PDF・画像出力を組み込むRust開発者

01

実装済みの機能

文書のスナップショット・出力データ・診断情報を扱う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をアプリ固有のUIへ直接結び付けず、KDVの文書フレーム・状態・診断として扱い、同じrender pipelineからHTML、PDF、PNG、JPEGを生成したい場合に向きます。viewer表示とexportの処理境界を共有できます。

図表を含む文書のexport準備

図表や数式を含むMarkdownをKDVでbuildし、図表renderはKRRへ委譲しながら、未対応の意味は診断とraw sourceとして保持できます。表示側で解釈できない入力を黙って捨てず、後段で扱える状態に残したい場合の基盤です。

02 / KDV

入力から出力までの流れ

  1. 入力を正規化

    入力ファイルを読み込み、CRLF/CRをLFへそろえ、Markdown fenceをMarkdownFenceNormalizerで正規化します。入力sourceにはURI、source kind、revision、本文を設定します。

  2. snapshotとbuild graphを作成

    KatanaMarkdownModel::parseでMarkdownを構造化し、DocumentSnapshotFactory::from_kmmでsnapshotを作ります。BuildRequestへmarkdown export profileとthemeを渡し、ForgePipeline::buildで診断を含むBuildGraphを生成します。

  3. artifactと診断を保存

    build graphをForgePipeline::exportへ渡して形式ごとのartifactを作り、build graph・coverage・summary TOMLとともに出力します。artifactが空なら実例のexport処理はエラーにして、利用者が不完全な成果物を受け取らない構造です。

03 / KDV

主要API・CLIの使い分け

DocumentSnapshotFactory
KMMの文書とDocumentSourceを組み合わせて、viewer/forgeが扱うDocumentSnapshotを作ります。入力本文だけでなくURIとrevisionもsnapshotの前提になります。
ForgePipeline::build
BuildRequestのsnapshot、BuildProfile、themeを処理し、文書snapshot・profile・diagnostics・rendered diagramsを持つBuildGraphを返します。
ForgePipeline::export
ExportRequestのbuild graph・形式・themeからExportOutputを返します。形式はHTML、PDF、PNG、JPEGで、artifactとforge diagnosticsを組み合わせて後段へ渡せます。
KRR diagram backend
DiagramRenderingBackendとKrrDiagramRenderEngineをpipelineへ渡すことで、図表renderをKRR境界へ接続します。KDV自身がアプリUIや別の図表実装を直接所有するAPIではありません。

04 / KDV

具体例で理解する

READMEをbuildして文書ノード数を確認する例

このコードはREADME.mdを読み、正規化・parse・snapshot化を行い、markdown export profileでBuildGraphを作ってノード数を表示します。公開export_debug実例からbuild部分を抜き出したもので、ファイルへの保存や4形式へのexportは実行しません。

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 backendを持ち込まない

KDVはegui/eframeなどのUI backendに依存せず、KUCの型も公開APIへ出しません。KatanAなどの上位アプリがviewerとeditorの同期指揮を担当し、KDVはdocument/viewer/export境界に集中します。

scaffoldingとして導入する

公開READMEの状態はscaffoldingで、v0.1.0はUI非依存のartifact/forge/export foundationです。KMMのparser gapsを再parseで埋めたり、KRR未対応の意味を完成済み機能として扱ったりしないことが導入条件です。

根拠

調査時点の公開リポジトリに基づく紹介です。リンク先の固定コミットで実装と手順を確認できます。

リポジトリREADME99371a97dbc5
根拠 · KDV
すべての製品