feat(pdf): Implement PDF Engine via Typst (Phase 25)

Add new utf8dok-pdf crate for PDF generation using Typst as the
typesetting backend:

- Transpiler: Converts utf8dok AST to Typst markup
  - Headings, paragraphs, lists, code blocks, tables
  - Inline formatting (bold, italic, monospace, etc.)
  - Links, images, quotes, admonitions
  - Template support via #import

- Compiler: Compiles Typst markup to PDF bytes
  - Uses typst-as-lib for embedded compilation
  - Custom font support via compile_with_fonts()

- CLI Integration:
  - New --format pdf option for render command
  - Template support with --template flag
  - Data includes support with --data-dir

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: alanbld

Cargo.toml

@@ -7,7 +7,7 @@ members = [
     "crates/utf8dok-wasm",
     "crates/utf8dok-ooxml",
     "crates/utf8dok-pptx",
-    "crates/utf8dok-diagrams", "crates/utf8dok-validate", "crates/utf8dok-plugins", "crates/utf8dok-lsp", "crates/utf8dok-data",
+    "crates/utf8dok-diagrams", "crates/utf8dok-validate", "crates/utf8dok-plugins", "crates/utf8dok-lsp", "crates/utf8dok-data", "crates/utf8dok-pdf",
 ]
 
 [workspace.package]

crates/utf8dok-cli/Cargo.toml

@@ -25,6 +25,7 @@ utf8dok-validate = { path = "../utf8dok-validate" }
 utf8dok-plugins = { path = "../utf8dok-plugins" }
 utf8dok-lsp = { path = "../utf8dok-lsp" }
 utf8dok-pptx = { path = "../utf8dok-pptx" }
+utf8dok-pdf = { path = "../utf8dok-pdf" }
 clap.workspace = true
 anyhow.workspace = true
 serde_json = "1.0"

crates/utf8dok-cli/src/app.rs

@@ -68,6 +68,8 @@ pub enum RenderFormat {
     Docx,
     /// PowerPoint presentation (.pptx)
     Pptx,
+    /// Portable Document Format (.pdf) via Typst
+    Pdf,
 }
 
 #[derive(Parser)]
@@ -723,6 +725,7 @@ pub fn render_command(
     match format {
         RenderFormat::Docx => render_docx(input, output, template, cover, data_dir),
         RenderFormat::Pptx => render_pptx(input, output, template, data_dir),
+        RenderFormat::Pdf => render_pdf(input, output, template, data_dir),
     }
 }
 
@@ -923,6 +926,72 @@ fn render_pptx(
     Ok(())
 }
 
+/// Render AsciiDoc to PDF via Typst
+fn render_pdf(
+    input: &std::path::Path,
+    output: Option<&std::path::Path>,
+    template: Option<&std::path::Path>,
+    data_dir: Option<&std::path::Path>,
+) -> Result<()> {
+    println!("  Format: PDF (via Typst)");
+
+    // Determine output path (default: input with .pdf extension)
+    let output_path = match output {
+        Some(p) => p.to_path_buf(),
+        None => input.with_extension("pdf"),
+    };
+
+    // Step 1: Read input AsciiDoc file
+    println!("  Reading: {}", input.display());
+    let source_content = fs::read_to_string(input)
+        .with_context(|| format!("Failed to read input file: {}", input.display()))?;
+
+    // Step 2: Parse AsciiDoc to AST (with optional data includes)
+    println!("  Parsing AsciiDoc...");
+    let ast = if let Some(base_path) = data_dir {
+        println!("    Data includes enabled: {}", base_path.display());
+        let config = ParserConfig::with_data_includes(base_path.to_string_lossy());
+        parse_with_config(&source_content, config).context("Failed to parse AsciiDoc content")?
+    } else {
+        parse(&source_content).context("Failed to parse AsciiDoc content")?
+    };
+    println!("    {} blocks parsed", ast.blocks.len());
+
+    // Step 3: Transpile AST to Typst markup
+    println!("  Transpiling to Typst...");
+    let typst_markup = if let Some(template_path) = template {
+        if template_path.exists() {
+            println!("    Using template: {}", template_path.display());
+            utf8dok_pdf::Transpiler::transpile_with_template(
+                &ast,
+                &template_path.display().to_string(),
+            )
+        } else {
+            eprintln!("  Warning: Template not found: {}", template_path.display());
+            utf8dok_pdf::Transpiler::transpile(&ast)
+        }
+    } else {
+        utf8dok_pdf::Transpiler::transpile(&ast)
+    };
+
+    // Step 4: Compile Typst to PDF
+    println!("  Compiling PDF...");
+    let pdf_bytes = utf8dok_pdf::Compiler::compile(&typst_markup)
+        .with_context(|| "Failed to compile Typst to PDF")?;
+
+    // Step 5: Write output
+    println!("  Writing: {}", output_path.display());
+    fs::write(&output_path, &pdf_bytes)
+        .with_context(|| format!("Failed to write output file: {}", output_path.display()))?;
+
+    println!();
+    println!("Render complete!");
+    println!("  Output: {}", output_path.display());
+    println!("  Size: {} bytes", pdf_bytes.len());
+
+    Ok(())
+}
+
 /// Execute the check command
 pub fn check_command(
     input: &std::path::Path,

crates/utf8dok-pdf/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "utf8dok-pdf"
+description = "PDF generation for utf8dok via Typst"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+keywords = ["pdf", "typst", "document", "generation"]
+categories = ["text-processing", "rendering"]
+
+[dependencies]
+utf8dok-ast = { path = "../utf8dok-ast" }
+typst-as-lib = "0.15"
+typst-pdf = "0.14"
+thiserror.workspace = true
+anyhow.workspace = true
+
+[dev-dependencies]
+tempfile = "3"

crates/utf8dok-pdf/src/compiler.rs

@@ -0,0 +1,116 @@
+//! Typst to PDF compiler
+//!
+//! Compiles Typst markup to PDF bytes using typst-as-lib.
+
+use crate::error::{PdfError, Result};
+use typst_as_lib::TypstEngine;
+
+/// Compiler for converting Typst markup to PDF
+pub struct Compiler;
+
+impl Compiler {
+    /// Compile Typst markup to PDF bytes
+    ///
+    /// # Arguments
+    /// * `markup` - Typst markup string
+    ///
+    /// # Returns
+    /// PDF bytes on success
+    pub fn compile(markup: &str) -> Result<Vec<u8>> {
+        Self::compile_with_fonts(markup, &[])
+    }
+
+    /// Compile with custom fonts
+    ///
+    /// # Arguments
+    /// * `markup` - Typst markup string
+    /// * `font_paths` - Paths to font files to include
+    ///
+    /// # Returns
+    /// PDF bytes on success
+    pub fn compile_with_fonts(markup: &str, font_paths: &[&str]) -> Result<Vec<u8>> {
+        // Build the Typst engine with the markup as main file
+        let mut builder = TypstEngine::builder().main_file(markup.to_string());
+
+        // Add fonts if provided
+        for font_path in font_paths {
+            let font_bytes = std::fs::read(font_path).map_err(|e| {
+                PdfError::Font(format!("Failed to read font {}: {}", font_path, e))
+            })?;
+            builder = builder.fonts([font_bytes]);
+        }
+
+        let engine = builder.build();
+
+        // Compile the document
+        let compiled = engine.compile();
+
+        // compiled is Warned<Result<Document, Error>>
+        // - compiled.output is the Result
+        // - compiled.warnings contains any warnings
+        let document = compiled
+            .output
+            .map_err(|e| PdfError::Compilation(format!("{:?}", e)))?;
+
+        // Generate PDF
+        let options = typst_pdf::PdfOptions::default();
+        let pdf_bytes = typst_pdf::pdf(&document, &options)
+            .map_err(|e| PdfError::Compilation(format!("PDF generation failed: {:?}", e)))?;
+
+        Ok(pdf_bytes.into())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_compile_simple() {
+        let markup = "= Hello World\n\nThis is a test document.";
+        let result = Compiler::compile(markup);
+
+        // Should compile successfully
+        assert!(result.is_ok(), "Compilation failed: {:?}", result.err());
+
+        let pdf = result.unwrap();
+        // PDF files start with %PDF
+        assert!(
+            pdf.starts_with(b"%PDF"),
+            "Output doesn't start with PDF header"
+        );
+    }
+
+    #[test]
+    fn test_compile_with_formatting() {
+        let markup = r#"
+= Document Title
+
+== Section One
+
+This is *bold* and _italic_ text.
+
+- Item one
+- Item two
+- Item three
+
+```rust
+fn main() {
+    println!("Hello!");
+}
+```
+"#;
+        let result = Compiler::compile(markup);
+        assert!(result.is_ok(), "Compilation failed: {:?}", result.err());
+    }
+
+    #[test]
+    fn test_compile_invalid_syntax() {
+        // This should still compile - Typst is quite forgiving
+        let markup = "#invalid_function_that_doesnt_exist()";
+        let result = Compiler::compile(markup);
+        // May fail or succeed depending on Typst version
+        // The important thing is it doesn't panic
+        let _ = result;
+    }
+}

crates/utf8dok-pdf/src/error.rs

@@ -0,0 +1,30 @@
+//! Error types for PDF generation
+
+use thiserror::Error;
+
+/// Result type for PDF operations
+pub type Result<T> = std::result::Result<T, PdfError>;
+
+/// Errors that can occur during PDF generation
+#[derive(Error, Debug)]
+pub enum PdfError {
+    /// Typst compilation error
+    #[error("Typst compilation failed: {0}")]
+    Compilation(String),
+
+    /// Font loading error
+    #[error("Font error: {0}")]
+    Font(String),
+
+    /// Template not found
+    #[error("Template not found: {0}")]
+    TemplateNotFound(String),
+
+    /// IO error
+    #[error("IO error: {0}")]
+    Io(#[from] std::io::Error),
+
+    /// Generic error
+    #[error("{0}")]
+    Other(String),
+}

crates/utf8dok-pdf/src/lib.rs

@@ -0,0 +1,71 @@
+//! utf8dok-pdf - PDF generation via Typst
+//!
+//! This crate provides PDF generation for utf8dok documents using Typst
+//! as the typesetting backend.
+//!
+//! # Architecture
+//!
+//! The PDF generation pipeline consists of two stages:
+//!
+//! 1. **Transpiler** - Converts `utf8dok_ast::Document` to Typst markup
+//! 2. **Compiler** - Compiles Typst markup to PDF bytes
+//!
+//! # Example
+//!
+//! ```ignore
+//! use utf8dok_ast::Document;
+//! use utf8dok_pdf::{Transpiler, Compiler};
+//!
+//! let doc = Document::new();
+//! let typst_markup = Transpiler::transpile(&doc);
+//! let pdf_bytes = Compiler::compile(&typst_markup)?;
+//! ```
+
+mod compiler;
+mod error;
+mod transpiler;
+
+pub use compiler::Compiler;
+pub use error::{PdfError, Result};
+pub use transpiler::Transpiler;
+
+/// Convenience function to render a document to PDF
+///
+/// # Arguments
+/// * `doc` - The AST document to render
+///
+/// # Returns
+/// PDF bytes on success
+pub fn render_pdf(doc: &utf8dok_ast::Document) -> Result<Vec<u8>> {
+    let typst_markup = Transpiler::transpile(doc);
+    Compiler::compile(&typst_markup)
+}
+
+/// Render with a custom template
+///
+/// # Arguments
+/// * `doc` - The AST document to render
+/// * `template_path` - Path to a .typ template file
+///
+/// # Returns
+/// PDF bytes on success
+pub fn render_pdf_with_template(
+    doc: &utf8dok_ast::Document,
+    template_path: &str,
+) -> Result<Vec<u8>> {
+    let typst_markup = Transpiler::transpile_with_template(doc, template_path);
+    Compiler::compile(&typst_markup)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_module_structure() {
+        // Verify exports are accessible
+        let _ = Transpiler::transpile;
+        let _ = Compiler::compile;
+        let _ = render_pdf;
+    }
+}