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.

§Typst compatibility

This release targets Typst 0.15. The re-exported typst crate is part of the public API, so moving to a new Typst version is a breaking change; see the README for the version compatibility table.

Re-exports§

pub use chrono_tz;chrono-tz
pub use time_tz;time-tz
pub use typst;
pub use typst_layout;
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. The recommended way to create one is with the error! or warning! macros.
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. The recommended way to create an error for this type is with the bail! macro.

Derive Macros§

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