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

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.