Biblioteca

KatanA Document Viewer

Biblioteca Rust para integrar en una aplicación la previsualización de documentos y la exportación a HTML, PDF e imágenes. Maneja datos documentales independientes del framework de UI.

Desarrolladores Rust que integran visores documentales o exportación HTML, PDF e imágenes

01

Funciones implementadas

API para snapshots documentales, datos de salida e información de diagnóstico

Fuentes

Conexión entre la estructura Markdown y el renderizado de diagramas mediante KRR

Fuentes

Exportación a HTML, PDF, PNG y JPEG

Fuentes

02

Primeros pasos

  1. Obtenga el repositorio y consulte el README para conocer el entorno y los requisitos de fuentes.
  2. Use el ejemplo export_debug indicando un archivo Markdown y un directorio de salida, y compruebe los documentos generados.

Prepare Rust y las herramientas de desarrollo necesarias y consulte el README enlazado para conocer los requisitos antes de integrar. Los ejemplos son puntos de entrada y no garantizan el funcionamiento en todos los entornos.

Fuentes
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

Casos de uso

Base común para mostrar y exportar documentos

Trate Markdown como marco, estado y diagnóstico documental de KDV, sin vincularlo directamente a la UI de la aplicación, para generar HTML, PDF, PNG y JPEG desde el mismo render pipeline. Puede compartir los límites de procesamiento entre la vista del viewer y la exportación.

Preparar la exportación de documentos con diagramas

Construya en KDV Markdown con diagramas y fórmulas, delegue el renderizado de diagramas a KRR y conserve los significados no soportados como diagnóstico y raw source. Así la entrada que la vista no puede interpretar no se descarta silenciosamente.

02 / KDV

Flujo de entrada a salida

  1. Normalizar la entrada

    Lea el archivo de entrada, convierta CRLF/CR a LF y normalice las Markdown fence con MarkdownFenceNormalizer. Configure URI, source kind, revision y el texto del source.

  2. Crear snapshot y build graph

    Estructure Markdown con KatanaMarkdownModel::parse y cree un snapshot mediante DocumentSnapshotFactory::from_kmm. Pase el markdown export profile y theme a BuildRequest y genere con ForgePipeline::build un BuildGraph que incluya diagnósticos.

  3. Guardar artifacts y diagnósticos

    Pase el build graph a ForgePipeline::export para crear el artifact de cada formato y escriba también el build graph, coverage y summary TOML. Si el artifact está vacío, el export real falla para no entregar un resultado incompleto.

03 / KDV

APIs y CLI principales

DocumentSnapshotFactory — Instantánea del documento
Combina el documento KMM con DocumentSource para crear el DocumentSnapshot que usan viewer/forge. El snapshot requiere también URI y revision, no solo el texto de entrada.
ForgePipeline::build — Construcción del grafo
Procesa el snapshot, BuildProfile y theme de BuildRequest y devuelve un BuildGraph con snapshot documental, profile, diagnostics y rendered diagrams.
ForgePipeline::export — Exportación de documentos
Devuelve ExportOutput a partir del build graph, formato y theme de ExportRequest. Los formatos son HTML, PDF, PNG y JPEG; artifact y forge diagnostics quedan disponibles para la siguiente etapa.
Backend de diagramas KRR
Conecte DiagramRenderingBackend y KrrDiagramRenderEngine al pipeline para llevar el render de diagramas al límite KRR. KDV no posee directamente la UI de la aplicación ni otra implementación de diagramas.

04 / KDV

Entender con un ejemplo

Construir README y comprobar sus nodos

El código lee README.md, normaliza CRLF/CR y las fences de Markdown, hace parse y crea un snapshot, y después construye un BuildGraph con el perfil de exportación Markdown antes de imprimir el número de nodos. Este ejemplo usa solo la parte de build de export_debug: no guarda archivos ni exporta los cuatro formatos; para eso debe ejecutarse el ejemplo export_debug aparte.

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

Integración y límites

No introducir un UI backend

KDV no depende de egui/eframe ni expone tipos KUC en su API pública. Aplicaciones superiores como KatanA coordinan la sincronización de viewer y editor con KMM, mientras KDV se concentra en document/viewer/export.

Adoptarlo como scaffolding

El estado público es scaffolding: v0.1.0 ofrece foundation de artifact/forge/export sin UI. No rellene gaps del parser de KMM con reparse ni trate como completas las semánticas que KRR aún no soporta; integre usando KMM y KRR en sus límites publicados.

Fuentes

Presentación basada en los repositorios públicos disponibles en el momento de la investigación. La implementación y los pasos se pueden comprobar en el commit fijado del enlace.

RepositorioLéame99371a97dbc5
Fuentes · KDV
Todos los productos