Antora UI Bundle Quick Reference

This is a condensed reference for the centralized UI bundle architecture. For full details, see Antora UI Architecture.

Architecture Overview

Antora UI Bundle Architecture

Common Tasks

Update Theme Colors or Styles

cd ~/atelier/_bibliotheca/domus-antora-ui

Edit the theme file:

vim src/css/domus-theme.css

Build and test locally:

npm run build

Commit and push:

git add -A && git commit -m "fix(theme): Description of change"
git push

Trigger docs rebuild (after UI build completes):

cd ~/atelier/_bibliotheca/domus-docs
git commit --allow-empty -m "chore: Rebuild with UI update"
git push

Update Navbar Menus

Edit the header partial:

vim src/partials/header-content.hbs

The navbar structure uses Handlebars:

<div class="navbar-item has-dropdown is-hoverable">
  <a class="navbar-link">Menu Name</a>
  <div class="navbar-dropdown">
    <a class="navbar-item" href="{{or siteRootPath '/'}}/component/version/page.html">Link Text</a>
  </div>
</div>

Add Theme Toggle Features

Edit the JavaScript:

vim src/js/vendor/domus-ui.js

Key Files

File Purpose

src/css/domus-theme.css

All custom theme styles (~900 lines)

src/js/vendor/domus-ui.js

Theme toggle, focus mode, code enhancements

src/partials/header-content.hbs

Custom navbar with dropdown menus

src/partials/head-styles.hbs

Early theme detection (prevents FOUC)

src/partials/footer-scripts.hbs

Script loading order

Theme CSS Structure

/* Base styles - apply to all themes */
body { background: var(--bg-primary) !important; }

/* Theme-specific overrides */
[data-theme="dark"] { /* dark theme vars */ }
[data-theme="catppuccin"] { /* mocha theme vars */ }
[data-theme="light"] { /* light theme vars */ }

CSS Variables

Variable Dark Catppuccin Light

--bg-primary

#1a1a1a

#1e1e2e

#ffffff

--bg-secondary

#252525

#313244

#f5f5f5

--text-primary

#e0e0e0

#cdd6f4

#1a1a1a

--accent-primary

#0077B6

#89b4fa

#0077B6

Troubleshooting

Page is white / Theme not applying

  1. Check if data-theme attribute is on <html>:

    document.documentElement.getAttribute('data-theme')
// Should return: "dark", "catppuccin", or "light"

  2. Hard refresh: Ctrl+Shift+R

  3. Clear theme cookie in DevTools → Application → Cookies → delete antora-theme

Styles not updating after push

  1. Verify UI bundle build completed (Cloudflare Pages → domus-ui → Deployments)

  2. Verify docs build completed (Cloudflare Pages → domus-docs → Deployments)

  3. Check build logs for errors

Bundle fetch failing in CI

Check build.sh output for:

ERROR: UI bundle is not a valid ZIP file

This means Cloudflare Access returned HTML login page instead of ZIP. Verify:

  • CF_ACCESS_CLIENT_ID is set correctly

  • CF_ACCESS_CLIENT_SECRET is set correctly

  • Service token hasn’t expired

Build Dependencies

1. Push to domus-antora-ui
2. Wait for Cloudflare Pages build (~1-2 min)
3. Push to domus-docs (or any trigger)
4. Wait for Cloudflare Pages build (~2-3 min)
5. Hard refresh browser

Environment Variables (Cloudflare Pages)

Set in domus-docs → Settings → Environment Variables:

Variable Purpose

CF_ACCESS_CLIENT_ID

Service token ID (from Zero Trust)

CF_ACCESS_CLIENT_SECRET

Service token secret

CF_ANTORA_GIT_TOKEN

GitHub PAT for private repos

Who Else Does This?

This centralized UI pattern is used by:

  • Red Hat - OpenShift, Ansible documentation

  • Couchbase - Database documentation

  • Apache - Multiple project docs

  • Mulesoft - API documentation

The Antora project explicitly recommends this approach for multi-repo documentation sites.

See Also