Skip to main content

Crate typst_template

Crate typst_template 

Source
Expand description

Generate PDFs with Typst straight from your Rust types.

Derive ToDict on a struct and it becomes a Typst input dictionary — feed it to a .typ template as sys.inputs and render to PDF, with no hand-written dict building. The ToValue / ToDict traits do the Rust-to-Typst value conversion, with optional chrono, time, rust_decimal, serde_json, and uuid support.

Rendering uses two parts:

  • WorldBase — built once; loads fonts and roots file access at a directory.
  • ConcreteWorld — one per document; attaches this generation’s sys.inputs and any virtual in-memory files (images, generated assets, …).

§Example

use typst_template::{ToDict, WorldBaseConfig};

#[derive(ToDict)]
struct Invoice {
    client: String,
    total: i64,
}

// A base that only uses the embedded fonts (no system font lookup).
let base = WorldBaseConfig::new(".").system_fonts(false).build();

let world = base
    .concrete("main.typ")
    .file("main.typ", "Invoice for #sys.inputs.client: #sys.inputs.total EUR")
    .inputs(Invoice { client: "ACME".into(), total: 42 })
    .build();

let pdf = world.render_pdf_default().output.expect("render succeeds");
assert_eq!(&pdf[..4], b"%PDF");

§Reusing a base

Build the WorldBase once, then derive a ConcreteWorld per document:

use typst_template::WorldBaseConfig;

let base = WorldBaseConfig::new(".").system_fonts(false).build();

for name in ["Alice", "Bob"] {
    let pdf = base
        .concrete("main.typ")
        .file("main.typ", "Hello, #sys.inputs.name!")
        .input("name", name)
        .build()
        .render_pdf_default()
        .output
        .expect("render succeeds");
    assert_eq!(&pdf[..4], b"%PDF");
}

§datetime.today()

With no chrono/time feature, datetime.today() is disabled by default and returns nothing; set a value with today. With chrono or time enabled it defaults to the system clock (today_system), and today_system_in (with chrono-tz or time-tz) pins “local” to a DST-aware named zone.

Note: with the time backend, today_system falls back to UTC when the OS-local offset is unavailable (e.g. in a multithreaded process); use a named zone (or chrono) for a specific local zone.

§Features

  • derive (default) — the ToDict derive macro.
  • chrono — ToValue for chrono date/time types, plus a system-clock datetime.today().
  • time — ToValue for time date/time types, plus a system-clock datetime.today(). chrono takes precedence if both are enabled.
  • chrono-tz / time-tz — named-time-zone support for today_system_in.
  • rust_decimal — ToValue for rust_decimal::Decimal.
  • serde_json — ToValue/ToDict for serde_json values.
  • uuid — ToValue for uuid::Uuid.

Re-exports§

pub use chrono_tz;chrono-tz
pub use time_tz;time-tz
pub use typst;
pub use typst_pdf;

Structs§

ConcreteWorld
A single-document world: a WorldBase plus this generation’s inputs and virtual files.
ConcreteWorldBuilder
Builder for a ConcreteWorld.
Dict
A map from string keys to values.
PdfOptions
Settings for PDF export.
SourceDiagnostic
An error or warning in a source or text file.
Str
A sequence of Unicode codepoints.
Warned
An output alongside warnings generated while producing it.
WorldBase
A long-lived, cheaply cloneable Typst world.
WorldBaseConfig
Builder for a WorldBase.
Zonechrono-tz or time-tz
A named time zone for today_system_in.

Enums§

Value
A computational value.

Traits§

ToDict
Converts a Rust struct into a Typst Dict.
ToValue
Converts a Rust value into a Typst Value.

Type Aliases§

SourceResult
A result that can carry multiple source errors.

Derive Macros§

ToDictderive
Derives ToDict (and, through it, ToValue) for a named struct. See the derive crate for the full list of #[typst(...)] attributes.