65 lines
3.2 KiB
Markdown
65 lines
3.2 KiB
Markdown
# Writing a Reportist plugin
|
|
|
|
A plugin is a self-contained way to turn one source format into a document.
|
|
It owns interpretation and layout, and can use the shared graphical elements.
|
|
The existing `plugins/report/` and `plugins/diagnostics/` are examples, not
|
|
schemas that every new plugin must imitate.
|
|
|
|
## Minimum contract
|
|
|
|
1. Give the plugin a stable kind name and document the input files it accepts.
|
|
Place its Typst source under `plugins/<kind>/`; keep normalization and
|
|
document composition in that plugin. Add a README with one standalone
|
|
render command and any required options.
|
|
2. Add a small shell entry point that stages the source, plugin Typst files,
|
|
themes, visual assets, and any plugin rules into a temporary directory,
|
|
runs Typst, and moves a completed PDF into place. Use
|
|
`tools/render-common.sh` for common options, path checks, `--force`, and
|
|
cleanup. Do not depend on a sibling repository or the macro checkout.
|
|
3. Route the kind through `build.sh render` and `render-all`. State its source
|
|
extensions in the batch filter; preserve relative paths. Extend `validate`
|
|
only if the plugin needs a separate validation command. If it produces a
|
|
non-PDF artifact, add an explicit command and document its contract.
|
|
4. Add a valid fixture, invalid-input and overwrite checks, and a standalone
|
|
render test in `tests/` or `plugins/<kind>/tests/`. Have `tests/test.sh`
|
|
run them. Update the macro integration checks only when macro publication
|
|
should include the new source set.
|
|
|
|
A typical plugin layout is:
|
|
|
|
```text
|
|
plugins/<kind>/
|
|
README.md
|
|
render.sh
|
|
renderer/render.typ
|
|
renderer/model.typ
|
|
renderer/normalize.typ # only if the input needs interpretation
|
|
runtime/ # optional rules or other plugin data
|
|
tests/ # fixtures and focused tests
|
|
```
|
|
|
|
## Boundaries to preserve
|
|
|
|
- `visual/elements.typ` and `visual/themes.yaml` are the shared visual
|
|
vocabulary. Add a reusable primitive there when several plugins need it;
|
|
keep page structure and plugin-specific presentation in the plugin.
|
|
- Read YAML/JSON, normalize values, validate domain facts, choose themes, and
|
|
assemble pages in Typst. Use shell or Python for directory traversal, safe
|
|
paths, hashes, temporary files, atomic replacement, and archives.
|
|
- Do not transform a new plugin's input into the authored report schema merely
|
|
to reuse `plugins/report/model.typ`. Share graphic elements instead.
|
|
- Keep input, intermediate evidence, and generated PDF distinct. The
|
|
diagnostic analyzer produces normalized evidence JSON, while the diagnostic
|
|
PDF renderer reads the raw capture. New plugins may have no intermediate.
|
|
- Reportist must render one input from its own checkout. The Reports repository
|
|
contains source content; the macro repository alone assembles publications.
|
|
|
|
## Review before merging
|
|
|
|
Run the plugin tests and `tests/test.sh` from Reportist. For changes to an
|
|
existing plugin, compare the approved fixture PDFs; the macro's current
|
|
regression suite checks 17 legacy outputs. Document intentional output changes
|
|
and update the oracle only after review. Run the macro `./beffroi.sh test` when
|
|
its stored sources or shared visual elements change. Keep both plugin behavior
|
|
and command examples in sync with `docs/build-cli.md`.
|