Plugins

on this page

What a plugin sees
Worked example
Trust

A plugin is a register(site) function in a oriel_plugins.py at the served folder root. It adds pages and tabs. oriel calls register(site) once at startup (and on hot-reload).

def register(site):
    @site.page("/status", "status", active=lambda: (site.root / "STATUS.md").exists())
    def status() -> str:                 # return an HTML body; oriel adds the chrome
        return site.markdown((site.root / "STATUS.md").read_text())

The page appears as a tab only while its optional active predicate returns true — so a dashboard vanishes when its data source isn't there.

What a plugin sees

member	meaning
`site.root`	the served folder, as a `Path`
`site.config`	the resolved config (all `oriel.toml` keys, including unknown ones)
`site.markdown(text)`	render Markdown to HTML (same renderer as the rest of oriel)
`site.page(route, label, active=None)`	decorator registering a page at `route`

A page function takes no arguments and returns an HTML body string; oriel wraps it in the nav, theme, and shell. Reading extra data files? Whitelist their URL prefix with extra_prefixes in oriel.toml so oriel will serve them.

Worked example

The bundled examples/oriel_plugins.py adds run-manifest and LLM-spend dashboards — a non-trivial plugin reading JSONL run logs and cost events straight from site.config.

Trust

A plugin is ordinary Python that oriel executes — the same trust level as serving the folder at all. Don't point oriel at a folder you don't trust.

Next: Math & LLM output.