typst-bake 0.1.3

Bake Typst templates, fonts, and packages into your Rust binary — use Typst as a self-contained, embedded library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

# typst-bake

[![Crates.io](https://img.shields.io/crates/v/typst-bake.svg)](https://crates.io/crates/typst-bake)
[![Documentation](https://docs.rs/typst-bake/badge.svg)](https://docs.rs/typst-bake)
[![CI](https://github.com/elgar328/typst-bake/actions/workflows/ci.yml/badge.svg)](https://github.com/elgar328/typst-bake/actions/workflows/ci.yml)
[![License](https://img.shields.io/crates/l/typst-bake.svg)](https://github.com/elgar328/typst-bake#license)

Bake Typst templates, fonts, and packages into your Rust binary — use Typst as a self-contained, embedded library.

## Features

- **Multi-Format Output** - Generate PDF, SVG, or PNG from the same template
- **Simple API** - Generate documents with just `document!("main.typ").to_pdf()`
- **Minimal Setup** - Just specify `template-dir` and `fonts-dir` in `Cargo.toml` metadata
- **File Embedding** - All files in `template-dir` are embedded and accessible from templates
- **Font Embedding** - Fonts (TTF, OTF, TTC) in `fonts-dir` are automatically bundled into the binary
- **Automatic Package Bundling** - Scans for package imports, downloads them at compile time, and recursively resolves all dependencies
- **Package Caching** - Downloaded packages are cached in system cache directory for faster compilation. Use `TYPST_BAKE_REFRESH=1` to force re-download
- **Runtime Inputs** - Pass dynamic data from Rust structs to Typst via `IntoValue` / `IntoDict` derive macros
- **Optimized Binary Size** - Resources are compressed with zstd and decompressed lazily at runtime
- **Smart Recompilation** - File changes trigger recompilation automatically, with optional build script for complete coverage

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
typst-bake = "0.1"

[package.metadata.typst-bake]
template-dir = "./templates"  # Path to your .typ files and assets
fonts-dir = "./fonts"         # Path to your font files
```

### Cargo Features

| Feature | Description |
|---------|-------------|
| `pdf` (default) | Enable `to_pdf()` |
| `svg` | Enable `to_svg()` |
| `png` | Enable `to_png()` |
| `full` | Enable all output formats |

PDF works out of the box. To disable PDF and use only SVG: `default-features = false, features = ["svg"]`.

### Optional: Complete File Change Detection

By default, `typst-bake` detects template or font file **modifications** and triggers recompilation when you run `cargo build`. File **additions and deletions** are not detected directly, but this is rarely an issue—adding a new file usually requires modifying an existing file (like `main.typ`) to use it, which triggers recompilation anyway.

If you want to fully detect even the rare case where you only add or remove files without modifying existing ones, add a build script:

```toml
# Cargo.toml
[package]
build = "build.rs"

[build-dependencies]
typst-bake = "0.1"
```

```rust
// build.rs
fn main() {
    typst_bake::rebuild_if_changed();
}
```

## Quick Start

```rust
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = typst_bake::document!("main.typ");

    // Generate PDF
    let pdf = doc.to_pdf()?;
    std::fs::write("output.pdf", &pdf)?;

    // Generate SVG
    let svgs = doc.to_svg()?;
    std::fs::write("page1.svg", &svgs[0])?;

    // Generate PNG at 144 DPI
    let pngs = doc.to_png(144.0)?;
    std::fs::write("page1.png", &pngs[0])?;

    Ok(())
}
```

For a complete walkthrough, see the [Quick Start Guide (PDF)](https://github.com/elgar328/typst-bake/blob/main/examples/quick-start/output.pdf). Also check out the PDF outputs from other examples below—each document explains its usage in detail.

## Examples

| Example | Description | Command | Output |
|---------|-------------|---------|--------|
| quick-start | Generates the Quick Start PDF using all features | `cargo run -p example-quick-start` | [PDF](https://github.com/elgar328/typst-bake/blob/main/examples/quick-start/output.pdf) |
| font-guide | Guide to font setup and usage | `cargo run -p example-font-guide` | [PDF](https://github.com/elgar328/typst-bake/blob/main/examples/font-guide/output.pdf) |
| with-inputs | Pass dynamic data from Rust to Typst | `cargo run -p example-with-inputs` | [PDF](https://github.com/elgar328/typst-bake/blob/main/examples/with-inputs/output.pdf) |
| with-files | Embed images and various data files | `cargo run -p example-with-files` | [PDF](https://github.com/elgar328/typst-bake/blob/main/examples/with-files/output.pdf) |
| with-package | Automatic package bundling | `cargo run -p example-with-package` | [PDF](https://github.com/elgar328/typst-bake/blob/main/examples/with-package/output.pdf) |
| output-formats | Multi-format output with rendering test patterns | `cargo run -p example-output-formats` | See below |

### output-formats Example Outputs

| Format | Files |
|--------|-------|
| PDF | [output.pdf](https://github.com/elgar328/typst-bake/blob/main/examples/output-formats/output.pdf) (42KB) |
| SVG | [output_1.svg](https://github.com/elgar328/typst-bake/blob/main/examples/output-formats/output_1.svg) (306KB), [output_2.svg](https://github.com/elgar328/typst-bake/blob/main/examples/output-formats/output_2.svg) (700KB) |
| PNG | [output_1.png](https://github.com/elgar328/typst-bake/blob/main/examples/output-formats/output_1.png) (388KB), [output_2.png](https://github.com/elgar328/typst-bake/blob/main/examples/output-formats/output_2.png) (693KB) |

## Comparison with typst-as-lib

**[typst-as-lib](https://github.com/Relacibo/typst-as-lib)** is a lightweight and flexible wrapper that makes it easy to use the Typst compiler as a Rust library. It supports various combinations of runtime filesystem access, package downloads from the internet, caching, and more.

**typst-bake** uses typst-as-lib internally, adding a layer focused on creating self-contained binaries. This focused scope enables a simple, easy-to-use API. It embeds all resources (templates, fonts, packages) into the binary at compile time, so the resulting executable works anywhere without external files or network access. For packages, the entire process—scanning, downloading, compressing, and embedding—is fully automatic.

### Key Differences

| Aspect | typst-as-lib | typst-bake |
|--------|--------------|------------|
| **Resources** | Runtime filesystem access or compile-time individual file embedding | Embeds entire folders at compile time |
| **Packages** | Runtime download (with caching) or local filesystem | Automatic scan, download, compress, and embed at compile time |
| **Fonts** | Typst default fonts, embedded fonts, system fonts, etc. | Embedded fonts only |
| **Configuration** | Flexible setup via builder pattern in code | Cargo.toml metadata only |
| **API** | Flexible with fine-grained control | Simple (`document!("main.typ").to_pdf()`) |

### Which should you use?

- If you want all resources embedded in your binary for a fully self-contained executable → use **typst-bake**
- If you prefer runtime flexibility (e.g., downloading packages on demand to reduce binary size) → use **typst-as-lib** directly

## License

MIT OR Apache-2.0