# 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: ```text 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.png` with your logo, or update the `logo` argument in `report.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: ```bash ./render.sh --all ``` ## Themes A report selects its theme by name: ```yaml 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: ```yaml 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: ```bash chmod +x render.sh ``` Alternatively, run it without changing permissions: ```bash bash render.sh reports/my-report.yaml ``` ## Continuous integration A minimal CI job only needs to install Typst and execute: ```bash ./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: ```bash ./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: ```gitignore build/ ``` PDFs intentionally stored outside `build/` remain trackable. ## Typical Git workflow ```bash 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](examples.md). ## 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](examples.md) if necessary. ### A report renders without a section Check the field name and nesting against [Writing reports](writing-reports.md). Optional empty or missing fields are intentionally omitted.