# 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//`; 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//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// 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`.