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

GitHub repository topics (facto-stack provider)

This playbook is a facto-stack hub, so it tags the provider only: facto-stack.

  • Not tagged: valentus-theme (the UI bundle is the pack’s paired theme and rolls on v2), and every pack member — page-context, site-nav-tree, soft-nav-page-toc, link-validator, linkinator, page-edit, antora-search-chat, nav-typology, build-stack, maint tools. package.json declares facto-stack and antora; maint scripts run through facto-maint.

  • Hub-owned: the supplemental-ui copies (partials, helpers, CSS, soft-nav.js) are local files, not pins. soft-nav-page-toc (pack extension) and soft-nav.js (hub script) are different things; see the policy page. Convention: Hub GitHub topics · Valentus GitHub Topics. Skill: antora-extension-consumers.

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

  • supplemental-ui/js/adt-table-scroll.js — wraps bare .tableblock tables for horizontal scroll (loaded from footer-content.hbs)

Wide AsciiDoc tables

Wide attribute tables and matrix layouts must stay inside the article column. Browsers cannot apply overflow-x: auto reliably on <table> alone, so the hub uses a scroll wrapper (Antora community guidance):

  • CSS (devcentr-brand.css): .tablecontainer and .adt-table-scroll are block-level with max-width: 100% and overflow-x: auto. Article flex children use min-width: 0 so the pane can shrink. Cell code and long tokens use overflow-wrap: anywhere; listing blocks get the same horizontal scroll treatment.

  • JS (adt-table-scroll.js): On DOMContentLoaded, each bare .doc table.tableblock not already inside .tablecontainer, .adt-table-scroll, .admonitionblock, or .colist is wrapped in <div class="adt-table-scroll" role="region" tabindex="0"> with an aria-label from the table caption (or Scrollable table).

Admonition and column-list tables are excluded so TIP/NOTE card chrome and colists keep their layout.

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.

Typology icon kill-switch (lab)

Diataxis / typology row icons render by default when nav_typology_diataxis is enabled. For local A/B rebuilds only, set site.keys.nav_typology_icons: 'false' to skip <svg><use> emission from nav-typology-icon (see Nav scroll performance A/B). Omit the key (or any value other than false) for production.

Related