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’ssys.inputsand 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) — theToDictderive macro.chrono—ToValueforchronodate/time types, plus a system-clockdatetime.today().time—ToValuefortimedate/time types, plus a system-clockdatetime.today().chronotakes precedence if both are enabled.chrono-tz/time-tz— named-time-zone support fortoday_system_in.rust_decimal—ToValueforrust_decimal::Decimal.serde_json—ToValue/ToDictforserde_jsonvalues.uuid—ToValueforuuid::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-tzpub use time_tz;time-tzpub use typst;pub use typst_layout;pub use typst_pdf;
Structs§
- Concrete
World - A single-document world: a
WorldBaseplus this generation’s inputs and virtual files. - Concrete
World Builder - Builder for a
ConcreteWorld. - Dict
- A map from string keys to values.
- PdfOptions
- Settings for PDF export.
- Source
Diagnostic - An error or warning in a source or text file. The recommended way to create
one is with the
error!orwarning!macros. - Str
- A sequence of Unicode codepoints.
- Warned
- An output alongside warnings generated while producing it.
- World
Base - A long-lived, cheaply cloneable Typst world.
- World
Base Config - Builder for a
WorldBase. - Zone
chrono-tzortime-tz - A named time zone for
today_system_in.
Enums§
- Value
- A computational value.
Traits§
Type Aliases§
- Source
Result - 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§
- ToDict
derive - Derives
ToDict(and, through it,ToValue) for a named struct. See the derive crate for the full list of#[typst(...)]attributes.