Recipes

Task-oriented workflows that combine the pieces documented elsewhere.

Self-updating figures

Treat figures as build products: reference fig.pdf from the slides, let a > build: hook regenerate it from your analysis script, and let the figures pipeline convert it to SVG on the fly:

> build: python figs.py

=== Results
! decay.pdf

Every build (and every save under revealer serve) reruns the script, so the deck can never drift out of sync with the data. See Figures pipeline for PDF→SVG caching and the details of build hooks.

Plots that match the theme

Every theme ships a palette-matched matplotlib style, copied into each deck at reveal.js/dist/theme/<theme>.mplstyle (slide-ready font sizes, the theme’s color cycle, no chartjunk):

# figs.py
import matplotlib.pyplot as plt

plt.style.use("reveal.js/dist/theme/revealer.mplstyle")

fig, ax = plt.subplots(figsize=(6, 4))
ax.plot(x, y, label="theory")
ax.set_xlabel(r"$t/\tau$")
ax.legend()
fig.savefig("Media/decay.pdf")

Combined with the recipe above, a theme change restyles the plots at the next build. To make your own theme (CSS variables + an .mplstyle), see Themes.

Managing citations

Point the deck at your BibTeX file once, cite per slide, and add an auto-generated bibliography section:

> bibtex: refs.bib

=== Related work
> cite: smith2026
A key result was reported<ref:smith2026>.

>>> biblio

Short citations appear in the slide footer; >>> biblio renders the full, paginated list. Details in Bibliography.

Assembling a lecture course with include

Keep each lecture in its own .pres and assemble master decks with > include::

# course.pres
>>> first: Statistical Physics — full course

> include: lecture-01/lecture-01.pres
> include: lecture-02/lecture-02.pres
> include: lecture-03/lecture-03.pres

  • Includes are expanded at build time, recursively; paths resolve relative to the including file and must stay inside the deck folder.

  • While serving the master deck, saving any included file rebuilds it — but included slides are read-only in the browser editor; serve the individual lecture to edit it there.

  • The same mechanism factors out a shared preamble (macros, settings) or a standard closing slide across many talks.

Reproducible decks

A presentation folder is self-contained and rebuildable years later:

  • .revealer.toml records the enabled extensions, the reveal.js version and the commit pins of every third-party plugin. Rebuilding or re-installing a deck (revealer update, an implicit setup) re-downloads exactly what is recorded — not whatever the plugins’ branches have moved to.

  • revealer update --force MyTalk deliberately re-pins to the versions shipped with your current Revealer and rewrites the record — the recommended way to migrate an old deck forward.

  • > macros:, > bibtex: and > build: all reference files inside the deck folder, so the folder (plus your figure scripts) is the complete archive of the talk. The .rv-history/ shadow repository created by the editor adds a local save history on top.

PDF handouts, one page per fragment

revealer pdf MyTalk exports one fully-revealed page per slide — right for a handout. For a PDF that steps through the talk the way the audience saw it, set:

> pdfSeparateFragments: true

and each fragment state becomes its own page. See revealer pdf for the export mechanics and requirements.