Skip to content

Rust library

The crate fagus is the engine the PHP package and the command line tool are built on. Use it to render PDFs inside a Rust program, without a separate process.

rust
let mut engine = fagus::Engine::new();
engine.add_font_dir("fonts")?;
let output = engine.render(&fagus::Document::html(html).base_directory("assets"))?;
std::fs::write("invoice.pdf", output.pdf)?;

Add the crate#

The crate is not published on crates.io. Depend on it from the Git repository, pinned to a release tag (releases are tagged v and their version) or to a commit with rev:

toml
[dependencies]
fagus = { git = "https://github.com/nforst/fagus", tag = "v0.1.0" }

A checkout of the repository works as a path dependency: fagus = { path = "../fagus/crates/fagus" }.

The crate needs Rust 1.97 or newer (edition 2024). Its code has no unsafe.

Features#

Feature Default Effect
parallel on Compresses the page contents on rayon's global thread pool while later pages are drawn

Without it (default-features = false), each document is written on one thread. With it, RAYON_NUM_THREADS or your own rayon::ThreadPoolBuilder::build_global() sets the size of the pool; the fagus binary uses two threads.

The engine#

An Engine holds the fonts, the parsed default style sheet and caches: faces loaded through @font-face (up to 256 MiB), decoded images and parsed style sheets are kept for the next documents. Create one and render many documents with it.

Method Description
Engine::new(), Engine::default() An engine with the built-in fonts (Inter regular and bold), which stand in where no other font fits
add_font_dir(&mut self, dir) -> Result<usize, Error> Adds the fonts (TTF, OTF, TTC, OTC, WOFF, WOFF2) in a directory and its subdirectories; returns the number of faces
add_font_data(&mut self, Vec<u8>) -> Result<usize, Error> Adds a font file's data (TTF, OTF, TTC, OTC, WOFF, WOFF2); returns the number of faces
add_system_fonts(&mut self) -> usize Adds the fonts installed on the machine, found as Chrome finds them; the output then depends on the machine
set_locale(&mut self, Option<String>) The language of the texts form controls show where the document gives no lang ("de-DE"); also the shaping language of text without lang and the PDF's language when <html> has none
set_generic_families(&mut self, sans_serif, serif, monospace) The families (Option<String> each) used for sans-serif, serif and monospace
render(&self, &Document) -> Result<Output, Error> Renders a document to PDF
render_with_diagnostics(&self, &Document) -> Result<Output, Failure> The same; a Failure has the error and the diagnostics found before it

Fonts, locale and generic families are described in fonts.md and php.md; the Rust methods behave as the PHP options of the same name.

Documents#

A Document is built with methods that take and return it. It is Clone, so one prepared document can be rendered with variations.

Method Description
Document::html(impl Into<String>) An HTML document
Document::xhtml(impl Into<String>) An XHTML document, parsed as XML
base_directory(impl Into<PathBuf>) The directory relative URLs resolve against; files are only read inside it (or root). Without it, no files are read
root(impl Into<PathBuf>) A larger directory files may be read from, which contains the base directory; URLs starting with / resolve against it. It takes effect only with a base directory
stylesheet(name, css) A style sheet after the document's own; name appears in diagnostics
resource(url, Vec<u8>) The data of a resource, by its URL as written in the document
loader(Arc<dyn ResourceLoader>) A loader for resources that are not handed over; asked before a file is read
conformance(Conformance) PDF/A
tagged(bool) Whether the PDF is tagged (default true)
accessible() PDF/UA-1
attach(Attachment) Attaches a file
factur_x(Vec<u8>) A ZUGFeRD / Factur-X invoice with this XML, its profile read from the XML
factur_x_profile(Vec<u8>, FacturXProfile) The same with the profile given
created(Date) The creation date (default: now), for reproducible output

What these options do to the PDF is described in pdf.md, how resources are found in resources.md.

The types they take:

  • Conformance: PdfA2b, PdfA2u, PdfA2a, PdfA3b, PdfA3u, PdfA3a. Conformance::from_level("3b") parses a name, name() gives "PDF/A-3b", is_tagged() says whether the level requires tags.
  • Attachment { name, mime_type, description: Option<String>, relationship, data: Arc<Vec<u8>> } with Relationship::{Source, Data, Alternative, Supplement, Unspecified}. PDF/A-3 and PDF/UA require a description.
  • FacturXProfile: Minimum, BasicWl, Basic, En16931, Extended, XRechnung. FacturXProfile::detect(&xml) reads the profile an XML declares.
  • Date { year, month, day, hour, minute, second } in UTC. Date::now() and Date::from_unix(seconds) make one; convert a local time to UTC before.

A document's metadata comes from its HTML (<title>, <html lang>, <meta>), see pdf.md; there is no method to set it.

Load resources#

A resource is looked for as a data: URL, among the resources handed over with resource(), through the loader, and last as a file inside the base directory or root. Fagus itself never goes to the network. Implement ResourceLoader to serve resources from a database, a cache or the network, under your own rules:

rust
use std::sync::Arc;

use fagus::{Document, ResourceLoader};

/// Answers with the files of the application's storage.
struct Storage;

impl ResourceLoader for Storage {
    fn load(&self, url: &str) -> Option<Vec<u8>> {
        let key = url.strip_prefix("storage://")?;
        std::fs::read(std::path::Path::new("assets").join(key)).ok()
    }
}

let document = Document::html(r#"<img src="storage://logo.svg" alt="Logo">"#)
    .loader(Arc::new(Storage));

load gets the URL exactly as written in the document and returns the data or None. The loader must be Send + Sync: it is called from the engine's rendering thread. The documents of frames ask for their resources by their URLs resolved against the frame's URL.

The output#

render returns an Output:

Field Type Content
pdf Vec<u8> The PDF file
pages usize The number of pages
diagnostics Vec<Diagnostic> CSS that was ignored, resources that are missing, warnings about the PDF
timings Timings parse, style, layout, paint and pdf, each a Duration

A Diagnostic has a severity (Severity::Info, Warning or Error, ordered so that severity >= Severity::Warning works), a stable code such as css.unknown-property, a message, a source (a file name, <style> 1, resources, pdf) and a 1-based line and column, 0 where unknown. Its Display writes it on one line:

text
<style> 1:12:3: warning[css.unknown-property]: unknown property `colr`; the declaration is ignored

Diagnostics never make render fail. To treat them as errors, check output.diagnostics yourself.

Errors#

render fails with fagus::Error:

Variant When
Error::Pdf The document does not meet PDF/A or PDF/UA (the message lists every problem), or the PDF could not be written
Error::Font A font could not be read (also from add_font_dir and add_font_data)
Error::Internal(String) A bug in Fagus: rendering stopped with a panic, which the engine caught

The types inside are exported too: Error::Pdf holds a fagus::PdfError, either PdfError::Conformance { standard, problems } (the standard, like PDF/UA-1, and the problems in words, separated by semicolons) or PdfError::Write(String); Error::Font holds a fagus::FontError, FontError::InvalidFont or FontError::Io(std::io::Error). Their Display gives the whole message:

rust
match engine.render(&document.accessible()) {
    Ok(output) => std::fs::write("letter.pdf", output.pdf)?,
    Err(fagus::Error::Pdf(error)) => eprintln!("refused: {error}"),
    Err(error) => return Err(error.into()),
}
// refused: the document does not meet PDF/UA-1: the document has no title (add a <title>); …

render_with_diagnostics fails with a fagus::Failure instead, which keeps the diagnostics found before the failure (an image that could not be loaded may explain why PDF/UA refuses the document). Its error is the Error that render returns, and it displays as that error:

rust
match engine.render_with_diagnostics(&document.accessible()) {
    Ok(output) => std::fs::write("letter.pdf", output.pdf)?,
    Err(failure) => {
        for diagnostic in &failure.diagnostics {
            eprintln!("{diagnostic}");
        }
        return Err(failure.error.into());
    }
}

Threads#

Engine, Document, Output, Error and Failure are Send and Sync. render takes &self, so one engine, shared by reference or in an Arc, renders documents from many threads at once:

rust
let pdfs = std::thread::scope(|scope| {
    let handles: Vec<_> = invoices
        .iter()
        .map(|html| scope.spawn(|| engine.render(&fagus::Document::html(html.as_str()))))
        .collect();
    handles
        .into_iter()
        .map(|handle| handle.join().expect("rendering thread").map(|output| output.pdf))
        .collect::<Result<Vec<_>, _>>()
})?;

The engine renders each document on a thread of its own with a large stack (64 MiB, reserved, used as needed), since deeply nested documents need more than the threads of most programs have. It keeps these threads for the next documents and adds one while all are busy, up to one per processor. render blocks until the document is done.

The methods that change the engine take &mut self: add fonts and settings before you share the engine. They apply to every document rendered after them.

A complete example#

An invoice with fonts of its own, an attachment and the Factur-X XML, as PDF/A-3b with a fixed date. assets/ holds invoice.html, invoice.xml and fonts/ (the HTML and XML of the example in pdf.md fit):

rust
use std::sync::Arc;

use fagus::{Attachment, Date, Document, Engine, Relationship, Severity};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut engine = Engine::new();
    engine.add_font_dir("assets/fonts")?;
    engine.set_locale(Some("de-DE".to_owned()));

    let html = std::fs::read_to_string("assets/invoice.html")?;
    let xml = std::fs::read("assets/invoice.xml")?;

    let document = Document::html(html)
        .base_directory("assets")
        .stylesheet("print.css", "body { color: #000 }")
        .factur_x(xml)
        .attach(Attachment {
            name: "timesheet.csv".to_owned(),
            mime_type: "text/csv".to_owned(),
            description: Some("Stundenzettel".to_owned()),
            relationship: Relationship::Supplement,
            data: Arc::new(b"date,hours\n2026-09-30,6\n".to_vec()),
        })
        .created(Date { year: 2026, month: 11, day: 1, hour: 8, minute: 0, second: 0 });

    let output = engine.render(&document)?;
    for diagnostic in &output.diagnostics {
        if diagnostic.severity >= Severity::Warning {
            eprintln!("{diagnostic}");
        }
    }
    std::fs::write("invoice.pdf", &output.pdf)?;
    println!("{} pages, layout took {:?}", output.pages, output.timings.layout);
    Ok(())
}

The command line tool in crates/fagus-cli is a larger example of the same API, and cli.md describes it.