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 視為 KDV 文件框架、狀態和診斷而不直接將其繫結到特定於應用程式的 UI,並且想要從同一渲染管道生成 HTML、PDF、PNG 和 JPEG 時,它非常適合。檢視器顯示和匯出處理邊界可以共享。
準備匯出包含圖形和表格的文件
您可以使用 KDV 構建包含圖表和公式的 Markdown,將圖表渲染委託給 KRR,並保留不支援的含義作為診斷和原始來源。當您希望將無法在顯示端解釋的輸入保留為稍後可以處理的狀態,而不是默默地丟棄它時,這是基礎。
02 / KDV
從輸入到輸出的流程
標準化輸入
讀取輸入檔案,把 CRLF/CR 統一為 LF,並用 MarkdownFenceNormalizer 規範化 Markdown fence。為輸入 source 設定 URI、source kind、revision 和正文。
建立 snapshot 和 build graph
用 KatanaMarkdownModel::parse 解析 Markdown,再用 DocumentSnapshotFactory::from_kmm 建立 snapshot。將 markdown export profile 和 theme 傳給 BuildRequest,通過 ForgePipeline::build 生成包含診斷資訊的 BuildGraph。
儲存工件和診斷
將構建圖傳遞給 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種格式。
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 尚不支援的語義當成已完成的能力。
依據
內容根據調查時點的公開儲存庫。可透過連結中的固定提交確認實作與使用方式。