Installation

There are several ways to add the dark theme to your Antora project.

Which installation path should I use?

  • If your project already uses Node/npm/pnpm (common for Antora sites) — Prefer Method 1 (npm registry) or Method 2 (GitHub as a package dependency). Both keep the theme in your package graph and lockfile. For custom supplemental UI on top of this theme, merge into a single directory or use virtual files (see Adding your own supplemental UI on top of this theme).

  • If you want no JavaScript install step (minimal CI, or a repo without Node) — Use Method 3 (pre-built ui-bundle.zip).

Method 1: npm registry (recommended)

Install the published package:

  • pnpm

  • npm

  • yarn

  • bun

pnpm add -D antora-dark-theme
npm install --save-dev antora-dark-theme
yarn add -D antora-dark-theme
bun add -D antora-dark-theme

Then configure your antora-playbook.yml with the Antora Default UI bundle and this theme’s supplemental files:

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

Adding your own supplemental UI on top of this theme

Antora’s ui.supplemental_files accepts either a single filesystem directory or an array of virtual files (path + contents). You cannot list multiple directories in the YAML array.

Merged directory (recommended): Copy node_modules/antora-dark-theme/supplemental-ui into your project (for example supplemental-ui/), merge your partials/, css/, and other assets, then set supplemental_files to that one path:

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

Pre-built theme bundle + virtual files: If you use the release ui-bundle.zip, the theme is already in the bundle; add only virtual supplemental_files entries for extra assets (see the Antora docs linked above).

Method 2: Install from GitHub as a package dependency

Useful for an unreleased commit or when you prefer the github: protocol:

  • pnpm

  • npm

  • yarn

# Latest default branch
pnpm add -D github:antora-supplemental/antora-dark-theme

# Specific tag
pnpm add -D github:antora-supplemental/antora-dark-theme#v0.1.0
npm install --save-dev github:antora-supplemental/antora-dark-theme
yarn add -D github:antora-supplemental/antora-dark-theme

Use the same supplemental_files path as Method 1 (./node_modules/antora-dark-theme/supplemental-ui).

Method 3: Pre-built UI bundle (no JavaScript toolchain)

Point your playbook at the release artifact (Antora Default UI + dark theme, no npm install):

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

Method 4: Install from release tarball

Download a specific .tgz from GitHub Releases if you need an exact version without using the npm registry:

  • pnpm

  • npm

  • yarn

pnpm add -D https://github.com/antora-supplemental/antora-dark-theme/releases/download/v0.1.0/antora-dark-theme-0.1.0.tgz
npm install --save-dev https://github.com/antora-supplemental/antora-dark-theme/releases/download/v0.1.0/antora-dark-theme-0.1.0.tgz
yarn add -D https://github.com/antora-supplemental/antora-dark-theme/releases/download/v0.1.0/antora-dark-theme-0.1.0.tgz

Then use the same playbook supplemental_files path as Method 1.

Method 5: Copy supplemental-ui folder

For maximum control, copy the supplemental-ui folder into your project:

  1. Clone or download the repository

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

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

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

Verify installation

Build your site to verify the installation:

antora antora-playbook.yml

Open the generated site in a browser. You should see a sun/moon toggle button in the navbar. Click it to switch between light and dark modes.