4.7 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
PDFs and exported ZIPs preserve the path beneath reports/, so
reports/2026/incidents/api-latency.yaml becomes
build/2026/incidents/api-latency.pdf. The top-level diagnostics/ output
folder is reserved; use another name for YAML report groups.
Use ./render.sh --clean --all to remove old report PDFs before rebuilding.
Diagnostic PDFs are cleaned separately with
./render-diagnostics.sh --clean --all "Your Name".
With a single input, --clean removes only its output PDF.
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.pngwith your logo, or update thelogoargument inreport.typ. - Change colors, typography, spacing, and components in
modules/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 config/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 config/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
modules/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:
- Build artifacts: Ignore
build/; PDFs are regenerated locally or in CI. - 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.