01
実装済みの機能
02
はじめ方
- リポジトリを取得し、READMEで実行環境とフォントの要件を確認します。
- export_debugの実例でMarkdownファイルと出力先を指定し、生成された文書を確認します。
Rustと必要な開発ツールを準備し、導入前にリンク先のREADMEで環境要件を確認してください。実行例は機能の入口であり、すべての環境での動作を保証するものではありません。
根拠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-output01 / KDV
どんな場面で使うか
文書表示と書き出しの共通基盤
Markdownをアプリ固有のUIへ直接結び付けず、KDVの文書フレーム・状態・診断として扱い、同じrender pipelineからHTML、PDF、PNG、JPEGを生成したい場合に向きます。viewer表示とexportの処理境界を共有できます。
図表を含む文書のexport準備
図表や数式を含むMarkdownをKDVでbuildし、図表renderはKRRへ委譲しながら、未対応の意味は診断とraw sourceとして保持できます。表示側で解釈できない入力を黙って捨てず、後段で扱える状態に残したい場合の基盤です。
02 / KDV
入力から出力までの流れ
入力を正規化
入力ファイルを読み込み、CRLF/CRをLFへそろえ、Markdown fenceをMarkdownFenceNormalizerで正規化します。入力sourceにはURI、source kind、revision、本文を設定します。
snapshotとbuild graphを作成
KatanaMarkdownModel::parseでMarkdownを構造化し、DocumentSnapshotFactory::from_kmmでsnapshotを作ります。BuildRequestへmarkdown export profileとthemeを渡し、ForgePipeline::buildで診断を含むBuildGraphを生成します。
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は実行しません。
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未対応の意味を完成済み機能として扱ったりしないことが導入条件です。
根拠
調査時点の公開リポジトリに基づく紹介です。リンク先の固定コミットで実装と手順を確認できます。