3.2 KiB
3.2 KiB
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
- 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. - 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.shfor common options, path checks,--force, and cleanup. Do not depend on a sibling repository or the macro checkout. - Route the kind through
build.sh renderandrender-all. State its source extensions in the batch filter; preserve relative paths. Extendvalidateonly if the plugin needs a separate validation command. If it produces a non-PDF artifact, add an explicit command and document its contract. - Add a valid fixture, invalid-input and overwrite checks, and a standalone
render test in
tests/orplugins/<kind>/tests/. Havetests/test.shrun them. Update the macro integration checks only when macro publication should include the new source set.
A typical plugin layout is:
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.typandvisual/themes.yamlare 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.