diff --git a/README.adoc b/README.adoc index d915d6d..d708407 100644 --- a/README.adoc +++ b/README.adoc @@ -50,7 +50,7 @@ This repository contains the Antora playbook and configuration for the **Dev Cen | `antora-playbook.yml` | Production Antora playbook. Uses remote GitHub URLs for all content sources and the published UI bundle. Used by CI/CD. | `antora-playbook-local.yml` | Local sibling-repo playbook (committed). Expects content repos as siblings (see the playbook `sources` list: `../devcentr`, `../switchyard`, `../msi-generator`, …). | `antora-playbook.testing.yml` | Same local content sources, but points `ui.bundle` at `../valentus-theme/build/ui-bundle.zip` for theme work. -| `supplemental-ui/` | Site overlay on the valentus-theme 2.x UI bundle: custom domain `CNAME`, accent-token brand CSS, header logo under `img/`, and a thin `head-meta.hbs` fork that loads the brand stylesheet. Header logo / navbar text use playbook `site.keys`. +| `supplemental-ui/` | Site overlay on the valentus-theme 2.x UI bundle: custom domain `CNAME`, accent-token brand CSS, header logo under `img/`, and a thin `head-meta.hbs` fork (FOUC paint-hold + preference boot scripts vendored from Valentus, plus the brand stylesheet link). Header logo / navbar text use playbook `site.keys`. | `.vscode/` | VS Code folder settings and extension recommendations for this playbook repo. | `package.json` | Defines dependencies and build scripts. |=== diff --git a/dark-mode-analysis.md b/dark-mode-analysis.md index 137bfd4..6c94b0e 100644 --- a/dark-mode-analysis.md +++ b/dark-mode-analysis.md @@ -10,6 +10,6 @@ Migrated from the retired `antora-dark-theme` package (2026-06). As of valentus-theme 2.x, header logo and navbar branding use playbook `site.keys` (for example `header_logo`) plus optional SVGs in `supplemental-ui/img/`. Search lives in the tool band (not the header). Consumers should not override `partials/header-content.hbs` for logo wiring alone; keep `head-meta.hbs` in sync with upstream when upgrading. -Color theming uses `supplemental-ui/css/devcentr-brand.css` (accent-token overrides), loaded from a thin `head-meta.hbs` fork (vendored from valentus so FOUC / dark-mode / read-width boot stay intact). Playbook `site.keys` stay snake_case; Antora camelCases them for the UI model. +Color theming uses `supplemental-ui/css/devcentr-brand.css` (accent-token overrides), loaded from a thin `head-meta.hbs` fork (vendored from valentus so FOUC paint-hold, dark-mode, read-width, and font-size boot stay intact). The interim `adt-fouc-pending` class hides the page until layered CSS and preference attrs apply; keep brand CSS in the stylesheet stack before the release script. Playbook `site.keys` stay snake_case; Antora camelCases them for the UI model. See `docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc`. diff --git a/docs/modules/ROOT/pages/activity-log.adoc b/docs/modules/ROOT/pages/activity-log.adoc index 254a11c..c504acc 100644 --- a/docs/modules/ROOT/pages/activity-log.adoc +++ b/docs/modules/ROOT/pages/activity-log.adoc @@ -8,6 +8,7 @@ This page records significant documentation and project activity at an org level === August +* **valentus-theme FOUC paint-hold** — Synced supplemental `head-meta.hbs` with Valentus interim paint-hold (`adt-fouc-pending`): hide until layered CSS and preference attrs apply, then release after read-width/font-size boot. Brand CSS stays in the stylesheet stack before the release script. xref:publishing/antora-ui-branding.adoc#fouc-paint-hold-interim[Antora UI branding]. * **AsciiDoc image alts + SVG encoding** — Unquoted `image::file.svg[A, B]` became HTML `width="B"`; opening some SVGs also hit XML *Encoding error* (non-UTF-8 / bare `&`). Quoted alts and rewrote Access/GCP SVGs as UTF-8 XML. xref:general-knowledge::how-to/cloudflare-access-static-site.adoc[Access how-to]. * **Access Finish setup + multi-org consent** — Cloudflare dashboard first, GitHub unlocked in the same browser; Authorize listing other orgs does not widen Access. xref:general-knowledge::how-to/cloudflare-access-static-site.adoc#finish-github-setup[Finish setup] · xref:general-knowledge::how-to/cloudflare-access-static-site.adoc#github-consent-other-orgs[Other orgs] · xref:tools/cloudflare-access.adoc[portal]. * **Language recommendations** — Small-set suggestions (D, Rust, TypeScript, Julia, Lisp/Haskell) plus reconstructed C/D, C++/D, Julia/D/Java, and D/Rust comparisons (dead Gemini shares). xref:general-knowledge::explanation/languages/index.adoc[Recommendations]. diff --git a/docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc b/docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc index a6a6a7f..1d74416 100644 --- a/docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc +++ b/docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc @@ -37,6 +37,21 @@ Do **not** override `partials/header-content.hbs` unless you need markup the the 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 link:https://gitlab.com/antora/antora-ui-default/-/merge_requests/207[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`: + +. Inline `html.adt-fouc-pending { visibility: hidden !important; }` plus a script that adds `adt-fouc-pending` on `` *before* stylesheets. +. All layered CSS links (fonts, `site-doc-layout.css`, `site-visual.css`, read-width, font-size, `devcentr-brand.css`, mermaid, math). +. Preference boot scripts (dark mode, read-width, font-size) that set `data-*` attrs / `dark-theme` from `localStorage`. +. A final script that removes `adt-fouc-pending` *after* those scripts run. + +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 [source,yaml] diff --git a/supplemental-ui/partials/head-meta.hbs b/supplemental-ui/partials/head-meta.hbs index 9675889..51aa995 100644 --- a/supplemental-ui/partials/head-meta.hbs +++ b/supplemental-ui/partials/head-meta.hbs @@ -1,5 +1,28 @@ +{{!-- + HACK (interim paint-hold): hide until layered CSS + preference attrs apply. + Copied from Valentus head-meta — pending upstream Default UI single-pass CSS + (antora-ui-default!207 + master FOUC/stylesheets guidance). Keep brand CSS + links with the other stylesheets, before the paint-hold release script. +--}} + + + + + + + + + +{{!-- DevCentr brand token overlay (after valentus visual CSS) --}} + + + - - - - - - - -{{!-- DevCentr brand token overlay (after valentus visual CSS) --}} - - - + {{#if page.origin.webUrl}} {{/if}}