Antora Dark Mode

A dark mode UI for Antora documentation sites.

Important

Use the GitHub release ui-bundle.zip (Default UI + this theme, pre-merged)—the habit every site should adopt. The npm package is deprecated and unpublished; see npm deprecation (archive & lessons learned). Discover this theme via Antora Supplemental docs (extensions registry).

Changelog: CHANGELOG.adoc (summaries) and changelog-details/ (dated detail files).

Contents

• Features
• Help Get Dark Mode into Antora
• Quick Start
  • The habit: release ui-bundle.zip
  • Version pinning (production vs. rolling lines)
  • Custom overrides (valid Antora options)
  • Vendor supplemental-ui in your repo
• Live Demo
• File Structure
• How It Works
  • 1. head-meta.hbs (Prevents Flash of Unstyled Content)
  • 2. footer-scripts.hbs (Loads the Toggle Script)
  • 3. site-dark-mode.js (Theme Toggle Logic)
  • 4. site-extra.css (Dark Mode Styles)
• Customization
  • Changing Colors
  • Adding More Styles
  • Changing the Toggle Button Position
  • Using a Custom Toggle Button
• Browser Support
• Compatibility
• Troubleshooting
  • Dark mode doesn’t persist
  • Toggle button doesn’t appear
  • Flash of light mode on page load
  • Some elements aren’t styled
• Contributing
• License
• Acknowledgments

Features

• Dark mode toggle - A sun/moon icon button in the navbar that switches between light and dark themes

• System preference detection - Automatically applies dark mode if the user’s OS is set to dark mode

• Persistent preference - Remembers the user’s choice via localStorage

• No FOUC (Flash of Unstyled Content) - Dark mode is applied before page render via inline script

• Non-invasive - Works as a supplemental UI overlay; no need to fork or rebuild the Antora default UI bundle

• Comprehensive styling - Covers navbar, navigation panels, content area, code blocks, tables, admonition blocks, footer, and more

• Version pinning strategies — exact semver pin (recommended for production), releases/latest, rolling line aliases (v1.0, v1.1, v1), supported-lines.json, and Renovate regex example; see the Version Pinning guide in the docs module.

Help Get Dark Mode into Antora

We’ve submitted this theme for inclusion in the official Antora Default UI. If you’d like to see native dark mode support in Antora, please upvote the feature request:

• [thumbs up] Upvote: Feature Request #216 - Dark Mode

Your support helps the Antora team prioritize this feature!

Doc-site chrome (mast, header layout, VCS icons) lives in the separate valentus-theme project. Pair valentus supplemental UI on top of this dark-mode release bundle when you want both.

Quick Start

Use the release bundle. That is the correct default—not a mild preference.

The habit: release ui-bundle.zip

Point your playbook at a pinned GitHub Release asset. You do not need this project on npm.

ui:
  bundle:
    url: https://github.com/antora-supplemental/antora-dark-mode/releases/download/v1.2.0/ui-bundle.zip
    snapshot: true
  supplemental_files: ./supplemental-ui-overrides

Optional supplemental_files is one directory of your files (logo, favicon)—not a second theme install.

Catalog and org docs: antora-supplemental.github.io/docs.

Former npm consumers: npm deprecation.

Warning

Antora accepts one supplemental directory or virtual files—not multiple directories in YAML.

See examples/antora-playbook.yml.

Version pinning (production vs. rolling lines)

GitHub Releases have no npm-style ranges in the URL. This theme documents three consumer strategies (float latest, exact pin, Renovate/~1.0.0) and publishes rolling prerelease aliases for line pins:

Playbook URL	Meaning
…​/releases/download/v1.2.0/ui-bundle.zip	Exact pin (recommended for CI)
…​/releases/download/v1.0/ui-bundle.zip	Latest v1.0.x patch (moving tag)
…​/releases/download/v1/ui-bundle.zip	Latest v1.x.x (moving tag)
…​/releases/latest/download/ui-bundle.zip	Newest semver release (includes major bumps)

Details: Version Pinning guide, supported-lines.json, examples/renovate.json.

Custom overrides (valid Antora options)

Antora’s ui.supplemental_files accepts either a single filesystem directory or an array of virtual files (path + contents). A YAML list of multiple directories is not supported—the array form is only for virtual entries.

Small override directory on the release bundle (typical: logo, favicon):

ui:
  bundle:
    url: https://github.com/antora-supplemental/antora-dark-mode/releases/download/v1.2.0/ui-bundle.zip
    snapshot: true
  supplemental_files: ./supplemental-ui-overrides

Merged directory (vendored fork): Copy supplemental-ui into your repo, merge your changes, then point the playbook at that one folder:

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: ./supplemental-ui

Virtual files: add single assets without a full supplemental tree:

  supplemental_files:
    - path: img/logo.svg
      contents: ./branding/logo.svg

Virtual override of a single UI file: Each entry must use path and contents (inline or path to a file on disk). If you replace a partial such as partials/head-meta.hbs, your file must still load this theme’s CSS and scripts (start from the theme’s partial), or use a merged directory instead.

Vendor supplemental-ui in your repo

If you want to vendor or heavily customize the dark mode assets, copy the supplemental-ui folder into your project from this repository.

1. Copy the folder:

   cp -r supplemental-ui /path/to/your/antora-project/

2. Point the playbook at your copy, on top of the default UI bundle:

   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: ./supplemental-ui

Live Demo

See the dark theme in action: Live Demo

File Structure

antora-dark-mode/
├── supplemental-ui/
│   ├── css/
│   │   └── site-extra.css      # Dark mode CSS styles
│   ├── js/
│   │   └── site-dark-mode.js   # Toggle button logic and theme management
│   └── partials/
│       ├── footer-scripts.hbs  # Loads the dark mode script
│       └── head-meta.hbs       # Loads CSS and prevents FOUC
├── docs/                        # Demo documentation
│   ├── antora.yml              # Component descriptor
│   └── modules/ROOT/
│       ├── nav.adoc            # Navigation
│       └── pages/              # Sample pages
├── examples/
│   ├── antora-playbook.yml     # Example playbook (release bundle; recommended)
│   └── antora-playbook-local.yml # Example playbook (bundle + optional overrides)
├── .github/workflows/
│   └── deploy.yml              # GitHub Pages deployment
├── antora-playbook.yml         # Playbook for demo site (online / CI)
├── antora-playbook-local.yml  # Local playbook (cached assets, no fetch)
├── package.json
├── LICENSE
└── README.adoc

How It Works

This theme uses Antora’s supplemental UI feature to overlay additional files onto the default UI bundle. The approach involves four key files:

1. head-meta.hbs (Prevents Flash of Unstyled Content)

This Handlebars partial is injected into the <head> of every page. It does two things:

• Loads the site-extra.css stylesheet

• Runs a tiny inline script that immediately applies the dark-theme class if the user previously selected dark mode or if their OS prefers dark mode

This prevents the brief flash of light mode before the main JavaScript loads.

<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-extra.css">
<script>
(function () {
  const themeKey = 'antora-theme';
  const savedTheme = localStorage.getItem(themeKey);
  if (savedTheme === 'dark' || (!savedTheme && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
    document.documentElement.classList.add('dark-theme');
  }
})();
</script>

2. footer-scripts.hbs (Loads the Toggle Script)

This partial is injected at the end of the page body. It loads the main site script, highlight.js, and the dark mode toggle script.

3. site-dark-mode.js (Theme Toggle Logic)

This JavaScript module:

• Injects a toggle button into the navbar (.navbar-end)

• Handles click events to switch between light and dark themes

• Persists the user’s preference in localStorage under the key antora-theme

• Updates the button icon (sun for dark mode, moon for light mode)

• Respects the user’s OS preference if no saved preference exists

4. site-extra.css (Dark Mode Styles)

The CSS file contains all dark mode styles using the selector prefix html.dark-theme. This explicit selector approach works because the Antora default UI’s compiled CSS doesn’t rely on CSS custom properties (variables) for theming.

Customization

Changing Colors

Edit supplemental-ui/css/site-extra.css to customize the color palette. The current theme uses these primary colors:

Variable	Value	Usage
Background (main)	#1a1b1e	Page body background
Background (elevated)	#25262b	Sidebar, navigation panels, blocks
Background (navbar)	#141517	Top navigation bar
Text (primary)	#c1c2c5	Main body text
Text (headings)	#ffffff	Headings and titles
Link color	#4dabf7	Hyperlinks
Link hover	#74c0fc	Hovered hyperlinks
Border color	#373a40	Dividers and borders

Adding More Styles

To style additional elements not covered by the default theme, add new selectors prefixed with html.dark-theme:

html.dark-theme .my-custom-element {
  background-color: #25262b;
  color: #c1c2c5;
}

Changing the Toggle Button Position

By default, the toggle button is inserted at the beginning of .navbar-end. To change its position, modify the ensureToggleButton() function in site-dark-mode.js:

// Insert at the end instead of the beginning
navbarEnd.appendChild(button);

Using a Custom Toggle Button

If you want to use your own toggle button markup, add an element with id="theme-toggle" anywhere in your page. The script will detect it and attach the click handler automatically.

Browser Support

This theme supports all modern browsers:

• Chrome/Edge (latest)

• Firefox (latest)

• Safari (latest)

• Opera (latest)

The theme uses standard CSS and JavaScript that works in all browsers supporting:

• localStorage

• classList

• matchMedia

Compatibility

Component	Version
Antora	3.x
Antora Default UI	Any version (HEAD recommended)
Node.js	18+

Troubleshooting

Dark mode doesn’t persist

Make sure localStorage is available and not blocked by browser settings or extensions. Check the browser console for errors.

Toggle button doesn’t appear

The toggle button is injected into .navbar-end. If your UI bundle has a different structure, you may need to modify the selector in site-dark-mode.js.

Flash of light mode on page load

Ensure head-meta.hbs is being loaded correctly. Check that the inline script isn’t being blocked by a Content Security Policy.

Some elements aren’t styled

The CSS covers the most common Antora elements. If you find unstyled elements, add selectors for them in site-extra.css with the html.dark-theme prefix.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

1. Fork the repository

2. Create a feature branch: git checkout -b feature/my-feature

3. Commit your changes: git commit -m "Add my feature"

4. Push to the branch: git push origin feature/my-feature

5. Open a pull request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

• The Antora team for creating an excellent documentation site generator

• The Antora Default UI which this theme extends

• Fossil SCM — acknowledged as a solid alternative to Git for version control; see the docs for a short discourse and plans for Dev-Centr support