Options

Options go on the figure (image attributes or code-block attributes) or project-wide under the livefigures metadata key.

Option	Values	Supported by	Default
theme	light, dark, auto	light/auto: all backends. dark: Excalidraw, Vega-Lite and Vega only — every other backend errors	auto (HTML), else light
background	transparent, scene	scene: Excalidraw, Vega-Lite and Vega only — every other backend errors	transparent

![Dark sketch](figures/arch.excalidraw){theme=dark background=scene}

livefigures:
  theme: light
  background: scene

Dark mode

theme: auto renders once (light). Excalidraw figures restyle on dark pages with the same CSS filter Excalidraw itself uses. Charts and diagrams with meaningful colors (Vega, Graphviz, …) deliberately stay light under auto — inverting data-encoded colors would misrepresent them; use an explicit theme=dark where the backend supports a true dark render (Excalidraw, Vega).

Backends without a dark or scene-background variant fail loudly if you ask for one — livefigures never silently renders something other than what you asked for.

WarningA project-wide theme: dark is a build-breaker

Setting theme: dark under the livefigures metadata key applies it to every figure, so any document containing a Graphviz, nomnoml, PlantUML or D2 figure aborts its render. Building a dark deck or site is exactly when this is tempting, and exactly when it bites.

Leave the project default alone and opt in per figure instead:

![Dark sketch](figures/arch.excalidraw){theme=dark}

Kroki endpoint

Kroki-backed formats (PlantUML, D2, …) render through kroki. The endpoint is configurable — self-host for private diagrams:

livefigures:
  kroki-url: "https://kroki.internal.example.org"

Network is needed only on cache misses; warm-cache rebuilds work offline. The endpoint participates in the cache key.

Captions and labels on inline blocks

```{.plantuml #fig-seq fig-cap="Login flow (markdown *works* here)"}
@startuml
Alice -> Bob: hello
@enduml
```