Antora UI branding (valentus-theme)

This documentation site uses the valentus-theme pre-built UI bundle (ui-bundle.zip). As of 2.0.0, the bundle ships dark mode, Lunr search in a tool band, read-width controls, Plus Jakarta Sans / Source Sans 3 / IBM Plex Mono, and a teal visual redesign. Site-specific branding is a thin supplemental-ui layer plus playbook site.keys.

Former antora-dark-theme consumers should migrate to this bundle URL.

Playbook

ui:
  bundle:
    url: https://github.com/antora-supplemental/valentus-theme/releases/download/v2/ui-bundle.zip
    snapshot: true
  supplemental_files: ./supplemental-ui

This repository carries the GitHub topic valentus-theme (product dependency rediscovery). Sites that adopt the same bundle should add that topic too — see the Valentus guide GitHub Topics.

DevCentr accent overlay

Layout, fonts, and default teal chrome stay valentus-theme. devcentr-brand.css remaps --adt-accent* tokens to the org palette and tints component-root nav expand/collapse chevrons (data-depth="0") with that accent — nested nav children keep Valentus muted ink toggles. Component roots do not use the generic component-root typology sprite; optional per-app logos come from nav-component-logo.js + supplemental-ui/img/nav-logos/. Deeper nav rows still use typology icons (Diátaxis, spec groupings, changelog). TIP/NOTE colors stay on Default UI / Valentus admonition tokens (--tip-color / --adt-admonition-tip — Antora green by default; do not remap tip to brand accent):

  • Light primary: #178F80

  • Dark primary: #2DD4BF

  • Logo accents: #14B8A6 / #0F766E

  • Nav-tree expand chevrons: component roots only → brand accent (replaces component-root typology icon); nested items → Valentus muted ink

  • Optional component logos: supplemental-ui/helpers/nav-component-logo.js + supplemental-ui/img/nav-logos/ (per Antora component name)

Overlay files:

  • supplemental-ui/css/devcentr-brand.css — accent token overrides (loaded last)

  • supplemental-ui/partials/head-meta.hbs — vendored from valentus-theme 2.x, plus the brand stylesheet link

  • supplemental-ui/img/logo.svg — orbit mark for the header

Do not override partials/header-content.hbs unless you need markup the theme keys cannot express. Upstream already reads camelCased site.keys for logo and navbar text.

When upgrading valentus-theme, re-diff head-meta.hbs against upstream and keep the brand CSS link after site-visual.css / site-read-width.css / site-font-size.css. The font-size FOUC script and stylesheet are required for the condensed A/A/A control (desktop hide + doc zoom).

FOUC paint-hold (interim)

Valentus 2.x ships an interim paint-hold in head-meta.hbs while Default UI single-pass CSS lands (see antora-ui-default!207 and upstream FOUC/stylesheets guidance). The supplemental overlay must stay in sync with that block.

Load order in supplemental-ui/partials/head-meta.hbs:

  1. Inline html.adt-fouc-pending { visibility: hidden !important; } plus a script that adds adt-fouc-pending on <html> before stylesheets.

  2. All layered CSS links (fonts, site-doc-layout.css, site-visual.css, read-width, font-size, devcentr-brand.css, mermaid, math).

  3. Preference boot scripts (dark mode, read-width, font-size) that set data-* attrs / dark-theme from localStorage.

  4. A final script that removes adt-fouc-pending after those scripts run — on this site, via document.fonts.load / document.fonts.ready with a 3s fallback if the CDN stalls.

Do not place the paint-hold release script before the brand or module stylesheets — users would see a flash of unstyled or wrong-accent chrome. Do not drop the read-width or font-size FOUC blocks; they are separate from the global paint-hold but must run before the release script.

When valentus-theme updates this partial, copy the upstream paint-hold comment block and release timing, then re-insert the devcentr-brand.css link in the stylesheet stack.

Header logo and navbar text

site:
  keys:
    header_logo: logo.svg
    site_home_url: https://devcentr.org
    site_home_label: DevCentr home
    header_doc_title: DevCentr Docs
Write playbook site.keys in snake_case. Antora camelCases them for the UI model (site_home_url → siteHomeUrl).

Place the logo at supplemental-ui/img/logo.svg.

The bundle detects repository URLs and maps them to provider icons under img/vcs/.

See the theme guide: VCS Repo Logo.

Related