165 lines
4.2 KiB
Markdown
165 lines
4.2 KiB
Markdown
# 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
|
|
```
|
|
|
|
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:
|
|
|
|
```bash
|
|
./render.sh --all
|
|
```
|
|
|
|
## Themes
|
|
|
|
A report selects its theme by name:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```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 `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
|
|
`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.
|