Installation

Requirements

  • Python ≥ 3.11 (the tomllib standard-library module is used to read configuration files).

  • pipx is recommended to install the command-line tool in an isolated environment.

For users

If you only want to use Revealer, install it with pipx:

git clone https://github.com/CandelierLab/Revealer.git
cd Revealer
pipx install .

This exposes the revealer command from any terminal.

To upgrade later, pull the latest changes and reinstall:

git pull
pipx install --force .

Python architecture and dependencies

You do not need to manage a virtual environment by hand. pipx install . creates an isolated environment for Revealer and installs all Python dependencies into it automatically:

  • typer, questionary, rich — the command-line interface;

  • tomli-w — writing the per-presentation configuration files;

  • bibtexparser — bibliography support.

This is why there is no separate pip install bibtexparser step any more: the package is declared as a dependency in pyproject.toml and lives in the pipx environment together with the revealer command.

Note

The historical python3 revealer.py <file>.pres invocation still works (it is used by the VS Code Run on save integration). It reuses the same package code under src/revealer/. Bibliography support then requires bibtexparser to be importable by that Python interpreter — installing the CLI with pipx and pointing Run on save at the pipx environment’s Python keeps everything in one place.

For developers

If you want to modify Revealer, install it in editable mode so that your changes take effect immediately, without ever running pipx uninstall/pipx install again:

git clone https://github.com/CandelierLab/Revealer.git
cd Revealer
pipx install --editable .

With an editable install, the revealer command runs the code straight from your working copy under src/revealer/. Any edit to a .py file, a theme (src/revealer/data/themes/), the runtime JavaScript (src/revealer/data/js/revealer.js) or the .pres template is picked up the next time you run a command — no reinstall needed.

Note

You only need to reinstall when pyproject.toml changes in a way that affects the environment (new dependency, renamed entry point):

pipx install --editable --force .

Iterating quickly

  • Python / CLI changes — just re-run revealer ...; the new code is used immediately.

  • Themes, JavaScript, .pres template — these assets are copied into a presentation’s reveal.js/ folder at build time, so rebuild the presentation (revealer build <file>.pres, or save it under Run on save) to apply them.

  • Documentation — build it locally with Sphinx:

    python3 -m venv .venv && source .venv/bin/activate
pip install -r Documentation/requirements.txt
sphinx-build -b html Documentation Documentation/_build/html

    Then open Documentation/_build/html/index.html.

Tip

If you prefer a plain virtual environment over pipx, the editable workflow is identical:

python3 -m venv .venv && source .venv/bin/activate
pip install --editable .

VS Code integration

Revealer pairs well with two VS Code extensions for a fast, near-WYSIWYG loop.

Run on save

Install the Run on save extension and add to your settings:

"emeraldwalk.runonsave": {
  "commands": [
    {
      "match": "\\.pres$",
      "cmd": "revealer build '${file}'"
    }
  ]
},
"files.associations": {
  "*.pres": "html"
}

Every time you save a .pres file, the matching .html is regenerated.

Live Server

Install the Live Server extension, open the generated .html file and click Go Live. The presentation reloads automatically on each save.

Optional VS Code extensions