typst_batch/
lib.rs

1//! # typst-batch
2//!
3//! A Typst → HTML batch compilation library with shared global resources.
4//!
5//! This crate was created for [tola](https://github.com/tola-ssg/tola-ssg),
6//! a Typst-based static site generator. It provides optimized batch compilation
7//! by sharing expensive resources across multiple document compilations:
8//!
9//! - **Fonts**: Loaded once (~100ms saved per compilation)
10//! - **Packages**: Downloaded once and cached globally
11//! - **File cache**: Fingerprint-based invalidation for incremental builds
12//! - **Standard library**: Shared instance with HTML feature enabled
13//!
14//! ## Note
15//!
16//! This library is specifically designed for **Typst → HTML** workflows.
17//! If you need PDF output or other formats, consider using typst directly
18//! or the official typst-cli.
19//!
20//! ## Quick Start
21//!
22//! ```ignore
23//! use typst_batch::{compile_html, get_fonts};
24//! use std::path::Path;
25//!
26//! // Initialize fonts once at startup
27//! get_fonts(&[]);
28//!
29//! // Compile a single file
30//! let result = compile_html(Path::new("doc.typ"), Path::new("."))?;
31//! std::fs::write("output.html", &result.html)?;
32//!
33//! // Compile with metadata extraction
34//! // In your .typ file: #metadata((title: "Hello")) <post-meta>
35//! let result = compile_html_with_metadata(
36//!     Path::new("post.typ"),
37//!     Path::new("."),
38//!     "post-meta",  // label name
39//! )?;
40//! println!("Title: {:?}", result.metadata);
41//! ```
42//!
43//! ## High-Level API
44//!
45//! For most use cases, use the high-level functions:
46//!
47//! - [`compile_html`]: Compile to HTML bytes
48//! - [`compile_html_with_metadata`]: Compile to HTML with metadata extraction
49//! - [`compile_document`]: Compile to HtmlDocument (for further processing)
50//! - [`query_metadata`]: Extract metadata from a compiled document
51//!
52//! ## Low-Level API
53//!
54//! For advanced use cases, access the underlying modules:
55//!
56//! - [`config`]: Runtime configuration (User-Agent for package downloads)
57//! - [`world`]: Typst World implementation
58//! - [`font`]: Font discovery and loading
59//! - [`mod@file`]: File caching and virtual file support
60//! - [`diagnostic`]: Error formatting
61
62#![forbid(unsafe_code)]
63#![warn(missing_docs)]
64
65pub mod compile;
66pub mod config;
67pub mod diagnostic;
68pub mod file;
69pub mod font;
70pub mod library;
71pub mod package;
72pub mod world;
73
74// =============================================================================
75// Prelude - import commonly used items with a single `use`
76// =============================================================================
77
78/// Prelude module for convenient imports.
79///
80/// Import everything commonly needed with:
81///
82/// ```ignore
83/// use typst_batch::prelude::*;
84/// ```
85///
86/// This includes:
87/// - Compilation functions: `compile_html`, `compile_document`, etc.
88/// - Diagnostics: `DiagnosticsExt`, `CompileError`
89/// - VFS: `VirtualFileSystem`, `MapVirtualFS`, `set_virtual_fs`
90/// - Fonts: `get_fonts`, `FontOptions`
91/// - World: `SystemWorld`
92pub mod prelude {
93    // Re-export common items from the crate root
94    // (avoids duplication - these are already exported at crate level)
95
96    // Compilation
97    pub use crate::{
98        compile_document, compile_document_with_inputs, compile_document_with_metadata,
99        compile_html, compile_html_with_inputs, compile_html_with_inputs_dict,
100        compile_html_with_metadata, query_metadata, query_metadata_map, DocumentResult,
101        HtmlResult,
102    };
103
104    // Diagnostics
105    pub use crate::{
106        CompileError, DiagnosticFilter, DiagnosticInfo, DiagnosticOptions,
107        DiagnosticSummary, DiagnosticsExt, DisplayStyle, SourceLine, TraceInfo,
108    };
109
110    // VFS
111    pub use crate::{
112        file_id, file_id_from_path, set_virtual_fs, virtual_file_id, MapVirtualFS,
113        NoVirtualFS, VirtualFileSystem,
114    };
115
116    // Fonts
117    pub use crate::{get_fonts, init_fonts_with_options, FontOptions};
118
119    // Library
120    pub use crate::create_library_with_inputs;
121
122    // World
123    pub use crate::SystemWorld;
124}
125
126// =============================================================================
127// High-Level API (recommended for most use cases)
128// =============================================================================
129
130pub use compile::{
131    compile_document, compile_document_with_inputs, compile_document_with_metadata,
132    compile_html, compile_html_with_inputs, compile_html_with_inputs_dict,
133    compile_html_with_metadata, query_metadata, query_metadata_map, DocumentResult,
134    DocumentWithMetadataResult, HtmlResult, HtmlWithMetadataResult,
135};
136
137// =============================================================================
138// Diagnostics
139// =============================================================================
140
141pub use diagnostic::{
142    // Error type
143    CompileError,
144    // Options for formatting
145    DiagnosticOptions, DisplayStyle,
146    // Filtering
147    DiagnosticFilter,
148    // Summary and extension trait (use .format(), .resolve(), etc.)
149    DiagnosticSummary, DiagnosticsExt,
150    // Structured data for custom rendering
151    DiagnosticInfo, SourceLine, TraceInfo,
152};
153
154// =============================================================================
155// Infrastructure
156// =============================================================================
157
158pub use config::{Config, ConfigBuilder};
159pub use file::{
160    clear_file_cache, file_id, file_id_from_path, get_accessed_files, is_virtual_path, read_virtual,
161    read_with_global_virtual, record_file_access, reset_access_flags, set_virtual_fs,
162    virtual_file_id, MapVirtualFS, NoVirtualFS, VirtualFileSystem, EMPTY_ID, GLOBAL_FILE_CACHE,
163    STDIN_ID,
164};
165pub use font::{
166    font_count, font_family_count, fonts_initialized, get_fonts, init_fonts_with_options,
167    FontOptions,
168};
169pub use library::{create_library_with_inputs, GLOBAL_LIBRARY};
170pub use world::SystemWorld;
171
172// =============================================================================
173// Re-export typst crates for advanced use
174// =============================================================================
175
176/// Full typst crate for advanced/custom compilation workflows.
177pub use typst;
178
179/// typst-html crate for HTML rendering.
180pub use typst_html;
181
182/// typst-kit for font/package utilities.
183pub use typst_kit;
typst_batch/lib.rs

typst_batch/
lib.rs
