| name | batch-render-typst |
| description | Batch-render N PDFs from a directory of JSON data files against a Typst template. Use when the user wants to render many documents at once (e.g. a month of invoices, a batch of certificates) using a Typst template they already have or just scaffolded. |
batch-render-typst
Render N PDFs in one pass: one Typst template + a directory of JSON payloads → one PDF per payload.
Inputs
- Template path —
.typ file. If the user just ran new-typst-template, default to that output.
- Data directory — folder of
*.json files, one per document.
- Output directory — where PDFs land. Default
<data-dir>/../out/.
- Concurrency (optional) — how many
typst compile processes to run in parallel. Default 4.
Pre-flight
- Verify
typst is on PATH. If not, instruct install (cargo install typst-cli or distro package). Do not auto-install.
- Verify the template uses the
#let data = json("data.json") pattern. If it hardcodes paths, fix or warn.
- Verify at least one JSON file exists in the data directory.
Approach
For each <data-dir>/*.json:
- Stage the file as
data.json next to the template (or use Typst's --input flag if the template supports sys.inputs).
- Run
typst compile <template.typ> <out-dir>/<basename>.pdf.
- Capture stdout/stderr. On failure, record the bad payload and continue.
Run with bounded parallelism (e.g. xargs -P or GNU parallel). Don't shell-out one process per doc serially for big batches.
Reporting
After the run:
- Total processed, succeeded, failed.
- Per-failure: filename + first line of error.
- Output directory path.
Write a render-report.json next to the output directory with the same data so downstream automation can consume it.
Storage rules
Template, data, and output paths are user-owned — they live wherever the user keeps them. The plugin only persists pointers and run history under $CLAUDE_USER_DATA_ROOT/state/last-batch.json (resolve via ${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/programmatic-doc-generation/).
