new-typst-template

new-typst-template

Scaffold a reusable Typst template parameterised over a JSON data file. The template is designed for batch rendering via the Typst CLI: one .typ template + N JSON files = N PDFs.

When to use

Auto-trigger when the user asks for a programmatic Typst template, especially for:

• Invoices, receipts, statements
• Reports with repeating sections (line items, transactions, attendees)
• Branded letters, certificates
• Anything where the same layout is rendered repeatedly with different data

If the user just wants a one-off styled document (not parameterised, not batch), the standalone typst skill is a better fit — point them to it instead.

Inputs to gather

1. Template type — invoice, receipt, statement, report, letter, certificate, custom.
2. Required fields — what variable data does the template consume? Get a list or a sample JSON. If the user has a sample document instead of a field list, route them to ingest-document-sample first.
3. Brand profile — check for $CLAUDE_USER_DATA_ROOT/brand.json (see path resolution below). If present, use it. If not, ask whether to run define-brand-profile first or proceed with placeholder branding.
4. Output directory — where the template files should live. Default: ask the user; suggest ~/Documents/doc-templates/<template-name>/.

Path resolution

Resolve the plugin data root once per session:

DATA_ROOT="${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/programmatic-doc-generation"
mkdir -p "$DATA_ROOT"

Read $DATA_ROOT/config.json for any pointers (e.g. user-chosen templates path). Read $DATA_ROOT/brand.json for brand profile, if present.

Template scaffold

For an invoice (other types follow the same pattern), produce:

<template-dir>/
├── template.typ          # the Typst template
├── data.example.json     # example payload — schema reference
├── render.sh             # batch render helper
└── README.md             # how to use, what each field does

template.typ should:

• Accept its data via #let data = json("data.json") at the top.
• Use brand colours/logo from the brand profile if available.
• Include a clearly commented "fields consumed" header listing every JSON path the template reads.
• Use Typst's #for over arrays (line items, sections) rather than hardcoded slots.

render.sh should iterate over a data/*.json directory and emit out/<basename>.pdf for each — one CLI call per file via typst compile.

After scaffolding

• Run typst compile once against the example data to verify it builds. If typst isn't installed, instruct the user how to install it (don't try to install it for them on a system you don't fully own).
• Tell the user how to add new data files and re-run render.sh, and point at batch-render-typst for the batch flow.

Storage rules

• Template files belong wherever the user chooses (their work, their data) — typically under ~/Documents/ or ~/repos/. Store only the path pointer in $DATA_ROOT/config.json.
• Never write template content into the plugin install directory.