This repository has been archived on 2026-09-16. You can view files and clone it, but cannot push or open issues or pull requests.
typst_reporter/docs/advanced-setup.md

4.2 KiB

Advanced setup

The default setup has no external Typst dependencies. These options are useful when the report archive or build process grows.

Nested report archives

./render.sh --all searches reports/ recursively. Reports can therefore be organized by year, month, customer, or project:

reports/
├── 2026/
│   ├── incidents/
│   │   └── api-latency.yaml
│   └── handoffs/
│       └── 2026-09-05.yaml
templates/
└── incident.yaml

To avoid rendering template YAML during --all, keep reusable templates outside reports/, for example in a top-level templates/ directory.

Customize branding and layout

  • Replace assets/beffroi.png with your logo, or update the logo argument in report.typ.
  • Change colors, typography, spacing, and components in model.typ.
  • Keep report-specific content out of the Typst model so historical YAML files remain reusable with later design changes.

After a model change, rebuild every report to check for regressions:

./render.sh --all

Themes

A report selects its theme by name:

theme: eridani

All themes live in the top-level themes.yaml registry. The built-in choices are default, cic, and eridani. To add one, copy an existing mapping, give it a new key, and adjust its values:

my_theme:
  label: "My Theme"
  font: "DejaVu Sans"
  mono_font: "DejaVu Sans Mono"
  ink: "#22262b"
  muted: "#66707a"
  line: "#d7dce1"
  paper_soft: "#f5f7f8"
  accent: "#34495e"
  info: "#385f7a"
  warning: "#8a671c"
  critical: "#7a3030"
  success: "#356344"

Color values use hexadecimal RGB notation. Fonts must be installed wherever the report is compiled; keeping the supplied DejaVu families is the most portable option for this repository. After editing themes.yaml, compile at least one representative report with each affected theme.

Image sources

Typst's image function accepts a local file path or image bytes; it does not download an image from an HTTP or HTTPS URL during compilation. Store required images under assets/ and commit them so local and CI builds remain reproducible. Remote URLs can still be printed as clickable links, but cannot be used directly as image sources.

Renderer permissions

If the script is not executable after cloning:

chmod +x render.sh

Alternatively, run it without changing permissions:

bash render.sh reports/my-report.yaml

Continuous integration

A minimal CI job only needs to install Typst and execute:

./render.sh --all

Treat any non-zero exit code as a failed build. Pin the Typst version in CI if reproducible output is important, and use the same version locally when changing model.typ.

For a lightweight local pre-commit check:

./render.sh --all
git diff --check

Generated PDF policy

Choose one policy and apply it consistently:

  1. Build artifacts: Ignore build/; PDFs are regenerated locally or in CI.
  2. Versioned archive: Commit PDFs beside each YAML change for immediate access and an immutable rendered snapshot.

This repository uses the build-artifact approach. Its .gitignore contains:

build/

PDFs intentionally stored outside build/ remain trackable.

Typical Git workflow

git pull
$EDITOR reports/2026/new-report.yaml
./render.sh reports/2026/new-report.yaml
git add reports/2026/new-report.yaml
git commit -m "Add incident report"
git push

Omit the copy step if you start from the boilerplate in Examples and boilerplate.

Troubleshooting

typst was not found

Install Typst and ensure typst --version works in the same shell used to run the renderer.

Report not found

Run the command from the repository root, or pass an absolute path. The renderer accepts paths relative to either the current directory or repository root.

YAML fails to parse

Check indentation, quote values containing punctuation, and use spaces rather than tabs. Start from a known-good file in Examples and boilerplate if necessary.

A report renders without a section

Check the field name and nesting against Writing reports. Optional empty or missing fields are intentionally omitted.