Antora UI Bundle Architecture

Overview

All Domus Digitalis documentation sites share a single, centrally managed UI bundle hosted on Cloudflare Pages and protected by Cloudflare Access.

Architecture

Antora UI Bundle Architecture

Components

domus-antora-ui Repository

Private GitHub repository containing the UI source code.

Location

github.com/EvanusModestus/domus-antora-ui (private)

Purpose

Custom Antora UI bundle with enterprise styling

Build

npm run build (Gulp pipeline)

Output

build/ui-bundle.zip

Key features:

  • Multi-theme support: Dark (default), Catppuccin Mocha, Light

  • Focus mode: Press F for distraction-free reading

  • Code enhancements: Language badges, copy buttons

  • Premium styling: Gold sidebars, executive summary tables

Cloudflare Pages (domus-ui)

Hosts the built UI bundle on Cloudflare’s global CDN.

Project

domus-ui

URL

ui.domusdigitalis.dev

Build command

npm run build

Output directory

build

Cloudflare Access Protection

The UI bundle is protected to prevent unauthorized access.

Application

antora-ui-bundle

Domain

ui.domusdigitalis.dev

Policy

CI Build Access (Service Auth)

Service Token

antora-ui-bundle

Configuration

Environment Variables

Set in Cloudflare Pages > domus-docs > Settings > Environment Variables:

Variable Purpose Required

CF_ANTORA_GIT_TOKEN

GitHub PAT for private repo access

Yes

CF_ACCESS_CLIENT_ID

Cloudflare Access service token ID

Yes

CF_ACCESS_CLIENT_SECRET

Cloudflare Access service token secret

Yes

domus-docs Build Script

The build.sh script in domus-docs:

  1. Validates required environment variables

  2. Fetches UI bundle with Access authentication

  3. Injects GitHub token into playbook URLs

  4. Runs Antora build

# Fetch UI bundle with Cloudflare Access auth
curl -sfo ui-bundle.zip \
    -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
    -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET" \
    https://ui.domusdigitalis.dev/ui-bundle.zip

Playbook Configuration

In antora-playbook.yml:

ui:
  bundle:
    # Domus Enterprise UI Bundle (fetched by build.sh with Access auth)
    url: ./ui-bundle.zip
    snapshot: true
  supplemental_files: ./supplemental-ui

Operations

Updating the UI

To update styling, themes, or functionality:

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

# Make changes to src/css/ or src/js/

# Build locally to test
npm run build

# Preview (optional)
npm run preview

# Commit and push
git add -A && git commit -m "feat(ui): Description of changes"
git push

Cloudflare Pages automatically rebuilds. All documentation sites get the new UI on their next build.

Triggering Documentation Rebuild

After UI changes, trigger a docs rebuild:

cd ~/atelier/_bibliotheca/domus-docs
git commit --allow-empty -m "chore: Trigger rebuild for UI update"
git push

Adding a New Documentation Repo

For new domus-* repos:

  1. Add to domus-docs/antora-playbook.yml:

    - url: https://github.com/EvanusModestus/domus-new-repo
  branches: main
  start_path: docs/asciidoc
  edit_url: false

  2. Push to trigger rebuild. New repo automatically uses the shared UI.

Troubleshooting

Build fails with "Failed to fetch UI bundle"

  1. Verify service token is valid (not expired)

  2. Check environment variables in Cloudflare Pages

  3. Verify service token has access to antora-ui-bundle application

UI changes not appearing

  1. Confirm domus-antora-ui build succeeded on Cloudflare Pages

  2. Trigger a rebuild of domus-docs

  3. Clear browser cache (UI is cached aggressively)

Access denied to ui.domusdigitalis.dev

  1. Verify service token is attached to the application policy

  2. Check Zero Trust > Access > Applications > antora-ui-bundle > Policies

  3. Ensure "CI Build Access" policy includes the service token

Security Considerations

  • UI bundle contains no secrets (CSS/JS/templates only)

  • Access protection adds defense-in-depth

  • Service tokens should be rotated periodically

  • Token credentials stored in age-encrypted secrets repo

Related Documentation