API Reference

Complete reference for the GlyphWeaveForge builder API, types, and configuration options.

pub struct Forge<'a> { /* private */ }

impl<'a> Forge<'a> {
    /// Creates a new builder with defaults:
    /// - backend: Minimal
    /// - page size: A4
    /// - layout: Paged
    /// - theme: Professional
    pub fn new() -> Self;

    /// Feed markdown from a string slice.
    pub fn from_text(self, md: &'a str) -> Self;

    /// Feed markdown from a byte slice (UTF-8).
    pub fn from_bytes(self, bytes: &'a [u8]) -> Self;

    /// Read markdown from a filesystem path (requires `fs` feature).
    pub fn from_path(self, path: &'a Path) -> Self;

    /// Write PDF to an explicit file path (requires `fs` feature).
    pub fn to_file(self, path: &'a Path) -> Self;

    /// Write PDF into a directory (requires `fs` feature).
    pub fn to_dir(self, dir: &'a Path) -> Self;

    /// Return PDF bytes in memory.
    pub fn to_memory(self) -> Self;

    /// Set a custom output file name (for directory targets).
    pub fn with_file_name(self, name: &'a str) -> Self;

    /// Choose a built-in theme.
    pub fn with_theme(self, theme: BuiltInTheme) -> Self;

    /// Merge a JSON object as theme overrides.
    pub fn with_theme_json(self, json: &'a str) -> Self;

    /// Select a renderer backend.
    pub fn with_backend(self, backend: RenderBackendSelection) -> Self;

    /// Set page size (A4, Letter, Legal).
    pub fn with_page_size(self, size: PageSize) -> Self;

    /// Set layout mode (Paged, SinglePage).
    pub fn with_layout(self, mode: LayoutMode) -> Self;

    /// Provide a closure that resolves image/resource paths.
    pub fn with_resource_resolver<F>(self, resolver: F) -> Self;

    /// Provide a pre-built ConvertOptions struct.
    pub fn with_options(self, opts: ConvertOptions<'a>) -> Self;

    /// Run the full conversion pipeline. Returns PdfOutput or ForgeError.
    pub fn convert(self) -> Result<PdfOutput>;
}

pub struct PdfOutput {
    /// The raw PDF bytes (always populated for to_memory).
    pub bytes: Option<Vec<u8>>,
    /// The file path where the PDF was written (for to_file / to_dir).
    pub path: Option<PathBuf>,
    /// Number of pages generated.
    pub pages: usize,
}

pub enum BuiltInTheme {
    Professional,       // Clean, modern defaults (default)
    Engineering,        // Monospace-friendly, blue accents
    ScientificArticle,  // Serif body, structured headings
    Invoice,             // Compact tables, right-aligned amounts
    Informational,       // High-contrast, accessible
}

pub enum PageSize {
    A4,       // 210 × 297 mm (default)
    Letter,   // 216 × 279 mm
    Legal,    // 216 × 356 mm
}

pub enum LayoutMode {
    Paged,       // Multi-page with breaks (default)
    SinglePage,  // Continuous single page
}

pub enum RenderBackendSelection {
    Minimal,   // Lightweight, zero system deps (default)
    Typst,     // Professional typesetting (requires renderer-typst feature)
}

pub enum ForgeError {
    MissingSource,               // No markdown source set
    MissingOutput,               // No output target set
    InputRead { path, source },  // File read failure
    InvalidUtf8(..),             // Non-UTF-8 bytes
    Parse { message },           // Markdown parse error
    Resource { target, msg },    // Resource resolution failure
    InvalidConfiguration { .. },  // Bad theme/config value
    RenderFailed { message },    // Backend renderer error
    UnsupportedFeature(..),      // Feature not enabled
}