Templates

Templates are Typst (.typ) files with optional JSON metadata files. They are stored in the templates/ directory.

Creating a Template

Using the UI

1. Click "New Template" on the Dashboard
2. Enter a template name (e.g., my-report)
3. Write your Typst markup in the editor
4. Use the Preview tab to see real-time PDF output as you type
5. Click Save

Using the API

# Create template with content and metadata
curl -X PUT http://localhost:3000/api/templates/my-report \
  -H "Content-Type: application/json" \
  -d '\''{
    "content": "#let data = json.decode(sys.inputs.at(\"data\"))\n= #data.title\n\n#data.body",
    "title": "My Report",
    "description": "A sample report",
    "exampleData": {
      "title": "Hello, World!",
      "body": "This is a sample report body."
    }
  }'\''

Template Metadata

Each template can have an associated JSON metadata file (saved as template-name.json alongside the .typ file):

{
  "title": "My Report",
  "description": "A sample report template",
  "exampleData": {
    "title": "Hello, World!",
    "body": "This is a sample report."
  }
}

Folder Organization

Templates can be organized in nested folders:

templates/
+-- universal-template.typ
+-- universal-template.json
+-- student/
�   +-- student-card.typ
�   +-- student-card.json
+-- academy/
    +-- enrolled-by-career.typ
    +-- students-by-condition.typ

Folders are created automatically when you save a template with a path separator (e.g., academy/enrolled-by-career).

Typst Variables

Data passed to templates is available as Typst variables. The full JSON object is available via sys.inputs:

#let data = json.decode(sys.inputs.at("data"))

#let title = data.title
#let date = data.date
#let items = data.items

You can customize the variable name using the variableName parameter in the API:

curl -X POST http://localhost:3000/api/report \
  -H "Content-Type: application/json" \
  -d '\''{
    "template": "my-report",
    "variableName": "reportData",
    "data": { "title": "Hello" }
  }'\''

In the template:

#let reportData = json.decode(sys.inputs.at("reportData"))

Best Practices

• Use the helper library for common patterns like tables and date formatting
• Keep templates focused on layout and styling, not data processing
• Use meaningful variable names in your JSON data
• Test templates with the live preview before generating reports
• Use subfolders to organize templates by project or report type