Antora Dark Theme

A dark mode supplemental UI theme for Antora documentation sites. This theme layers on top of the Antora Default UI without requiring modifications to the base UI bundle.

Contents

• Features
• Help Get Dark Mode into Antora
• Quick Start
  • Method 1: Use pre-built bundle (Recommended)
  • Method 2: Copy supplemental-ui folder
  • Method 3: Use as npm dependency
• 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

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:

• https://gitlab.com/antora/antora-ui-default/-/issues/216[[thumbs up]

Your support helps the Antora team prioritize this feature!

Quick Start

Method 1: Use pre-built bundle (Recommended)

The easiest way to use this theme is to point your Antora playbook directly to the latest pre-built UI bundle. This includes the Antora Default UI plus all dark mode enhancements.

1. Configure your antora-playbook.yml to use the release bundle:

   ui:
     bundle:
       url: https://github.com/the-dev-center/antora-dark-theme/releases/latest/download/ui-bundle.zip
       snapshot: true

Method 2: Copy supplemental-ui folder

If you want to customize the dark mode styles or logic locally, you can copy the supplemental-ui folder into your project.

1. Copy the supplemental-ui folder to your project root:

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

2. Configure your antora-playbook.yml to use the supplemental files alongside the default UI:

   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

Method 3: Use as npm dependency

You can also install this theme as a dev dependency. This is useful for version tracking and easy updates within your project’s ecosystem.

npm

npm install --save-dev antora-dark-theme

pnpm

pnpm add -D antora-dark-theme

Yarn

yarn add -D antora-dark-theme

Bun

bun add -D antora-dark-theme

Then reference the supplemental UI from node_modules:

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

Live Demo

See the dark theme in action: Live Demo

File Structure

antora-dark-theme/
├── 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 (npm install)
│   └── antora-playbook-local.yml # Example playbook (direct copy)
├── .github/workflows/
│   └── deploy.yml              # GitHub Pages deployment
├── antora-playbook.yml         # Playbook for building demo site
├── 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