Configuration

The dark theme works out of the box with sensible defaults. This page covers the configuration options available.

Playbook Configuration

The only required configuration is adding the supplemental files to your antora-playbook.yml:

ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
  supplemental_files: ./node_modules/antora-dark-theme/supplemental-ui

Default Behavior

Theme Detection

The theme automatically detects your preference in this order:

  1. Saved preference - If you’ve previously toggled the theme, that choice is remembered

  2. System preference - If no saved preference exists, the theme checks your OS dark mode setting

  3. Light mode - Falls back to light mode if neither of the above applies

Storage Key

The theme stores your preference in localStorage under the key antora-theme. Values are either light or dark.

To programmatically set the theme:

// Set dark mode
localStorage.setItem('antora-theme', 'dark');
location.reload();

// Set light mode
localStorage.setItem('antora-theme', 'light');
location.reload();

// Clear preference (use system default)
localStorage.removeItem('antora-theme');
location.reload();

File Structure

The supplemental UI consists of four files:

supplemental-ui/
├── css/
│   └── site-extra.css      # Dark mode CSS styles
├── js/
│   └── site-dark-mode.js   # Toggle button logic
└── partials/
    ├── footer-scripts.hbs  # Loads the dark mode script
    └── head-meta.hbs       # Loads CSS and prevents FOUC

Each file serves a specific purpose:

site-extra.css

Contains all dark mode styles using the html.dark-theme selector prefix.

site-dark-mode.js

Injects the toggle button and handles theme switching logic.

head-meta.hbs

Handlebars partial injected into <head> that loads CSS and prevents flash of unstyled content.

footer-scripts.hbs

Handlebars partial that loads the JavaScript at the end of the page body.