Command-line tool

The revealer command manages presentations and the reveal.js engine they embed. It is a hybrid CLI: explicit sub-commands, with interactive menus (extension selection, presentation picker) where it helps.

Direct open

The fastest entry point: give revealer a .pres file (or a folder containing one) with no sub-command, and it behaves as revealer serve — build, open in the browser with live reload, editor enabled:

revealer talk.pres          # same as: revealer serve talk.pres
revealer ~/talks/MyTalk     # a folder works too

Interactive menu

Running revealer with no argument opens a navigable menu giving access to every feature:

revealer

Revealer — reveal.js scientific presentations

? What would you like to do?
 » Edit a presentation (live preview + editor)
   Load a presentation (open a .pres in the browser)
   Build a presentation
   Create a new presentation
   Manage extensions
   Update the reveal.js engine
   List presentations
   Set or show the presentations root
   Quit

Use the arrow keys to navigate and Enter to select; each entry runs the corresponding action (asking for any extra input, such as a presentation to pick or extensions to toggle) and then returns to the menu. Choose Quit (or press Ctrl-C) to leave.

Load a presentation lets you browse to any .pres file (or its folder), even one that does not live under the root — it builds the deck, opens it in your browser, and remembers it (see recents below). The presentation picker used by the other actions also offers a 📂 Load a presentation… entry, so you can always reach a deck outside the root.

Every menu entry has an equivalent sub-command, documented below, for scripted or non-interactive use.

Configuration

Revealer stores a small global configuration in ~/.config/revealer/config.toml (following the XDG base directory spec). Its main role is to remember your presentations root — the folder where all your presentations live.

It also keeps a short recents list: every presentation you load (via the menu or revealer open) is remembered there, so it shows up in revealer list and in the presentation picker even if it lives outside the root. (Discovery under the root only scans its direct child folders, so decks nested deeper are reached via Load / recents.)

Each presentation also carries a hidden .revealer.toml file recording the reveal.js extensions it uses, the reveal.js version, and the commit pins of its third-party plugins, so the engine can be rebuilt or updated identically later (see Recipes › Reproducible decks).

Commands

revealer root [PATH]

Set or display the presentations root folder.

revealer root ~/Science/Presentations   # set
revealer root                           # show current value

revealer new NAME

Scaffold a new presentation under the root: a folder, a freshly downloaded reveal.js engine with the chosen extensions, and a pre-filled NAME.pres file. You are prompted to select the extensions interactively.

revealer new MyTalk
revealer new MyTalk --here   # create in the current directory instead

revealer open [TARGET]

Load a presentation: build it, remember it in recents, and open the result in your browser. TARGET may be a .pres file or its folder; omit it to pick from the list (which includes a Load… browse entry).

revealer open ~/talks/MyTalk/MyTalk.pres   # build + open in the browser
revealer open ~/talks/MyTalk               # a folder works too
revealer open --no-show MyTalk.pres        # build + remember only, no browser
revealer open                              # pick / browse interactively

revealer select

Interactively pick an existing presentation from the root and build it.

revealer list

Show a table of the presentations found in the root and their enabled extensions.

revealer plugins [TARGET]

Choose the extensions for a presentation (interactive checkbox), then download any missing plugins, refresh index.html and rebuild. TARGET may be a presentation folder or a .pres file; if omitted you are asked to pick one.

revealer update [TARGET]

Update the reveal.js engine of a presentation to the version pinned by Revealer, keeping its extensions.

revealer update MyTalk
revealer update MyTalk --force   # re-download reveal.js from scratch

The --force flag is the recommended way to migrate older presentations to the current reveal.js version and plugin set.

revealer build [TARGET]

Generate the HTML presentation from a .pres file. This is the command used by the VS Code Run on save integration.

revealer serve [TARGET]

Serve a presentation with rebuild-on-save and live browser reload. TARGET may be a .pres file or its folder; --port / -p picks the port (default 8000, auto-incremented if busy) and --no-open skips launching the browser.

revealer serve MyTalk            # build, open, watch
revealer serve MyTalk -p 9000    # explicit port

While the server runs, every save of the .pres (or of the deck’s media, .bib, .svg files) rebuilds and reloads the browser in place, keeping the current slide and fragment. Build errors appear as an overlay in the browser — with an open in editor button (uses $REVEALER_EDITOR, VS Code’s code -g, or $EDITOR) — while the last good version keeps being served. The server binds to 127.0.0.1 only and serves a separate <name>.dev.html artifact, deleted on exit; the exported <name>.html is not touched.

The served presentation carries the browser editor’s toolbar (edit mode, undo/redo, fragment drawer, outline, media import, split view, save history, HTML/PDF export) — see The browser editor.

revealer pdf [TARGET]

Export a presentation to PDF, one page per slide with every fragment visible (revealer export is the same command under another name). TARGET may be a .pres file or its folder; --out / -o sets the output path (default: next to the .pres).

revealer pdf MyTalk               # -> MyTalk/MyTalk.pdf
revealer pdf MyTalk -o slides.pdf

The export drives a headless Chrome/Chromium (it must be installed, along with the img2pdf command); each slide is captured at the presentation resolution and the pages are assembled losslessly. This avoids the blank pages produced by the stock reveal.js ?print-pdf route with Revealer’s fitted layout.

By default every slide becomes one page with all fragments shown. Set > pdfSeparateFragments: true in the .pres settings block to get one page per fragment state instead (the pre-fragment state, then each step), matching what the audience sees during the talk.

How updating works

reveal.js and its plugins are not bundled inside the repository. Instead, Revealer keeps a pinned manifest of:

• the reveal.js core release (which ships the official plugins: markdown, highlight, notes, zoom, math, search);

• third-party plugins, with their source repository and pinned reference: chalkboard, customcontrols, anything (from rajgoel/reveal.js-plugins) and embed-video (from ThomasWeinert/reveal-embed-video).

revealer new, revealer plugins and revealer update download exactly the pinned versions and wire the selected extensions into index.html, so every presentation is reproducible.