라이브러리

KatanA Document Viewer

문서 프리뷰와 HTML·PDF·이미지 출력을 앱에 통합하는 Rust 라이브러리입니다. UI 프레임워크에 의존하지 않는 문서 데이터를 다룹니다.

문서 viewer와 HTML·PDF·이미지 출력을 통합하는 Rust 개발자

01

구현된 기능

문서 snapshot·출력 artifact·diagnostic 정보를 다루는 API

근거

Markdown 문서 구조와 KRR 다이어그램 렌더링을 연결하는 처리

근거

HTML·PDF·PNG·JPEG export

근거

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를 결합해 후속 단계로 넘길 수 있습니다.
DiagramRenderingBackend — 도표 렌더링 연결
DiagramRenderingBackend와 KrrDiagramRenderEngine을 pipeline에 전달해 도표 render를 KRR 경계에 연결합니다. KDV가 앱 UI나 별도의 도표 구현을 직접 소유하는 API는 아닙니다.

04 / KDV

구체적인 예

README를 build하고 문서 노드 수 확인하기

이 코드는 README.md를 읽고 정규화·parse·snapshot화를 수행한 뒤 markdown export profile로 BuildGraph를 만들어 노드 수를 표시합니다. 공개 export_debug 실제 예제에서 build 부분만 가져온 것이며 파일 저장이나 네 형식으로의 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이 지원하지 않는 의미를 완성 기능으로 취급하지 않는 것이 도입 조건입니다.

근거

조사 시점의 공개 저장소를 바탕으로 소개합니다. 링크된 고정 커밋에서 구현과 사용 방법을 확인할 수 있습니다.

저장소읽기 안내99371a97dbc5
근거 · KDV
모든 제품