docs: add workflow documentation for CSS sync process

Document the GitHub Actions workflow that synchronizes boostlook.css across boostlook, website-v2, and website-v2-docs repositories. Includes high-level overview, detailed technical reference, branch strategy, and troubleshooting guide. https://claude.ai/code/session_01E9Mz7zZRPiVNn234U4dbXa
feat: add search input and results dropdown styling (#142 )
2026-01-27 18:52:13 +00:00 · 2026-01-26 19:13:07 +00:00 · 2026-01-16 02:49:40 -05:00 · 2025-12-28 07:07:37 -05:00 · 2025-12-18 16:31:19 -05:00 · 2025-12-16 14:32:25 -05:00
8 changed files with 670 additions and 54 deletions
--- a/.github/workflows/sync-boostlook-css.yml
+++ b/.github/workflows/sync-boostlook-css.yml
@@ -16,10 +16,10 @@ jobs:
    if: github.repository == 'boostorg/boostlook'
    steps:
      - name: Checkout current repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Checkout website-v2 repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          repository: boostorg/website-v2
          ref: develop
@@ -29,7 +29,7 @@ jobs:
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
-          python-version: "3.11"
+          python-version: "3.13"

      - name: Copy boostlook.css to website-v2
        run: |
--- a/MonaspaceNeon-Regular.woff2
+++ b/MonaspaceNeon-Regular.woff2
--- a/MonaspaceNeon-Var.woff2
+++ b/MonaspaceNeon-Var.woff2
--- a/MonaspaceRadon-Italic.woff2
+++ b/MonaspaceRadon-Italic.woff2
--- a/MonaspaceXenon-Italic.woff2
+++ b/MonaspaceXenon-Italic.woff2
--- a/MonaspaceXenon-Var.woff2
+++ b/MonaspaceXenon-Var.woff2
--- a/boostlook.css
+++ b/boostlook.css
@@ -280,8 +280,8 @@
  --main-container: 90rem;

  /* New Look Typography */
-  --font-family-body: "Noto Sans";
-  --font-family-code: "Noto Sans Mono";
+  --font-family-body: "Noto Sans", system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif;
+  --font-family-code: "Monaspace Neon", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
  --font-size-3xs: 0.625rem;
  --font-size-2xs: 0.75rem;
  --font-size-xs: 0.875rem;
@@ -709,7 +709,7 @@ html:has(.boostlook) {
 * Typography Configuration
 * The framework uses Noto Sans family as its primary font system:
 * 1. Noto Sans Display: Main text font with variable weight support
- * 2. Noto Sans Mono: Monospace font for code blocks
+ * 2. Monaspace Neon: Monospace font for code blocks
 *
 * Font Loading Strategy:
 * - Multiple source paths for resilient loading
@@ -723,13 +723,16 @@ html:has(.boostlook) {
  font-style: normal;
  font-weight: 100 900;
  font-stretch: 62.5% 100%;
-  /* Variable font weight range */
  font-variation-settings: "wght" 400, "wdth" 62.5;
  font-display: block;
-  /* Prevents FOIT */
-  src: url("/static/font/notosans.woff2") format("woff2"),
-  url("../../../../tools/boostlook/notosans.woff2") format("woff2"),
-  url("https://cppalliance.org/fonts/NotoSansDisplay.ttf") format("truetype");
+  src: url("../font/NotoSansDisplay.ttf") format("truetype"),
+    url("/static/font/notosans.woff2") format("woff2"),
+    url("../../../../tools/boostlook/notosans.woff2") format("woff2"),
+    url("https://cppalliance.org/fonts/NotoSansDisplay.ttf") format("truetype");
+  size-adjust: 100%;
+  ascent-override: 92%;
+  descent-override: 22%;
+  line-gap-override: 0%;
 }

 /* Noto Sans Display - Italic */
@@ -738,42 +741,48 @@ html:has(.boostlook) {
  font-style: italic;
  font-weight: 100 900;
  font-stretch: 62.5% 100%;
-  /* Variable font weight range */
  font-variation-settings: "wght" 400, "wdth" 62.5;
  font-display: block;
-  /* Prevents FOIT */
-  src: url("/static/font/notosans_mono_ext.woff") format("woff"),
-  url("../../../../tools/boostlook/notosans_mono_ext.woff") format("woff"),
-  url("https://cppalliance.org/fonts/NotoSansMono.ttf") format("truetype");
+  src: url("../font/NotoSansDisplay-Italic.ttf") format("truetype"),
+    url("/static/font/notosans_ext.woff2") format("woff2"),
+    url("../../../../tools/boostlook/notosans_ext.woff2") format("woff2"),
+    url("https://cppalliance.org/fonts/NotoSansDisplay-Italic.ttf") format("truetype");
+  size-adjust: 100%;
+  ascent-override: 92%;
+  descent-override: 22%;
+  line-gap-override: 0%;
 }

-/* Noto Sans Mono - Variable Weight */
+/* Monaspace Neon - Regular */
@font-face {
-  font-family: "Noto Sans Mono";
-  font-style: normal;
-  font-weight: 100 900;
-  font-stretch: 62.5% 100%;
-  /* Variable font weight range */
-  font-variation-settings: "wght" 400, "wdth" 62.5;
-  font-display: block;
-  /* Prevents FOIT */
-  src: url("/static/font/notosans_mono.woff") format("woff"),
-  url("../../../../tools/boostlook/notosans_mono.woff") format("woff"),
-  url("https://cppalliance.org/fonts/NotoSansMono.ttf") format("truetype");
-}
-
-/* Noto Sans Mono - Fixed Weight */
-@font-face {
-  font-family: "Noto Sans Mono";
+  font-family: "Monaspace Neon";
  font-style: normal;
  font-weight: 400;
-  /* Fixed weight for specific use cases */
-  font-stretch: 62.5% 100%;
  font-display: block;
-  /* Prevents FOIT */
-  src: url("/static/font/notosans_mono.woff") format("woff"),
-  url("../../../../tools/boostlook/notosans_mono.woff") format("woff"),
-  url("https://cppalliance.org/fonts/NotoSansMono.ttf") format("truetype");
+  src: url("../font/MonaspaceNeonFrozen-Regular.ttf") format("truetype"),
+    url("/static/font/MonaspaceNeon-Var.woff2") format("woff2"),
+    url("../../../../tools/boostlook/MonaspaceNeon-Var.woff2") format("woff2"),
+    url("https://cppalliance.org/fonts/MonaspaceNeon-Var.woff2") format("woff2");
+  size-adjust: 100%;
+  ascent-override: 92%;
+  descent-override: 22%;
+  line-gap-override: 0%;
+}
+
+/* Monaspace Xenon - Italic */
+@font-face {
+  font-family: "Monaspace Xenon";
+  font-style: italic;
+  font-weight: 400;
+  font-display: block;
+  src: url("../font/MonaspaceXenonFrozen-Italic.ttf") format("truetype"),
+    url("/static/font/MonaspaceXenon-Var.woff2") format("woff2"),
+    url("../../../../tools/boostlook/MonaspaceXenon-Var.woff2") format("woff2"),
+    url("https://cppalliance.org/fonts/MonaspaceXenon-Var.woff2") format("woff2");
+  size-adjust: 100%;
+  ascent-override: 92%;
+  descent-override: 22%;
+  line-gap-override: 0%;
 }

 /*----------------- Font-Face Declarations end -----------------*/
@@ -852,6 +861,8 @@ h6 {
 body :not(pre):not([class^="L"]) > code {
  /* ovverrides builtin colors */
  color: var(--text-code-neutral, #0d0e0f);
+  border: 0;
+  background-color: unset;
 }

 /* Stacking context */
@@ -1258,15 +1269,17 @@ div.source-docs-antora.boostlook:not(:has(.doc)):not(:has(>.boostlook)) > #conte
  cursor: pointer;
 }

-/* Link States */
-.boostlook p a:visited:not(:hover),
-.boostlook table a:visited:not(:hover) {
-  color: var(--text-main-text-body-tetriary, #62676b);
+/* Emphasis within code */
+.boostlook code em,
+.boostlook code i,
+.boostlook pre em,
+.boostlook pre i {
+  font-family: "Monaspace Xenon", monospace;
+  font-size: inherit;
+  font-style: italic;
 }

-/* Emphasis within code */
-.boostlook em,
-.boostlook code em {
+.boostlook em {
  font-family: inherit;
  font-size: inherit;
  font-style: italic;
@@ -1276,6 +1289,20 @@ div.source-docs-antora.boostlook:not(:has(.doc)):not(:has(>.boostlook)) > #conte
 .boostlook b,
 .boostlook strong {
  font-variation-settings: "wght" 600, "wdth" 80;
+  text-shadow: none;
+}
+
+/* Comments within code (inline and blocks) */
+.boostlook code span.c,
+.boostlook code span.ch,
+.boostlook code span.cm,
+.boostlook code span.cp,
+.boostlook code span.cpf,
+.boostlook code span.c1,
+.boostlook code span.cs,
+.boostlook code span.comment {
+  font-family: "Monaspace Xenon", monospace;
+  font-style: italic;
 }

 /* Code Block Styling */
@@ -1294,7 +1321,7 @@ div.source-docs-antora.boostlook:not(:has(.doc)):not(:has(>.boostlook)) > #conte
 }

 .boostlook code {
-  font-family: var(--font-family-code, "Noto Sans Mono"), monospace;
+  font-family: var(--font-family-code, "Monaspace Neon"), monospace;
 }

 .boostlook table thead code {
@@ -1306,6 +1333,7 @@ div.source-docs-antora.boostlook:not(:has(.doc)):not(:has(>.boostlook)) > #conte
 .boostlook .doc .content pre code,
 .boostlook .doc pre.highlight code {
  font-size: var(--typography-font-size-xs, 0.875rem);
+  font-feature-settings: "calt" 1, "liga" 0;
  line-height: var(--typography-line-height-lg, 1.5rem); /* 171.429% */
  letter-spacing: var(--spacing-size-size-0, 0rem);
  color: var(--text-main-text-primary, #18191b);
@@ -1332,10 +1360,23 @@ div.source-docs-antora.boostlook:not(:has(.doc)):not(:has(>.boostlook)) > #conte
 .boostlook .doc .content pre,
 .boostlook .doc pre.highlight,
 .boostlook .doc .listingblock pre:not(.highlight),
-.boostlook .doc .literalblock pre {
+.boostlook .doc .literalblock pre
+.boostlook .literalblock pre,
+.boostlook .listingblock > .content > pre,
+.boostlook .listingblock > .content > pre:not(.highlight),
+.boostlook .literalblock > .content > pre:not(.highlight),
+.boostlook .exampleblock > .content,
+.boostlook .sidebarblock {
  padding: var(--spacing-size-xs, 0.75rem) var(--spacing-size-sm, 1rem);
-  background: var(--atom-one-light-bg, #fafafa);
+  background: var(--atom-one-light-bg, #fafafa) !important;
  border-radius: 0;
+  border: none;
+  box-shadow: none;
+}
+
+.boostlook .sidebarblock {
+  margin-top: 20px;
+  border: 1px solid var(--border-border-secondary, #d5d7d9);
 }

 /* Dark theme code block background */
@@ -1344,8 +1385,17 @@ html.dark .boostlook pre.rouge,
 html.dark .boostlook .doc .content pre,
 html.dark .boostlook .doc pre.highlight,
 html.dark .boostlook .doc .listingblock pre:not(.highlight),
-html.dark .boostlook .doc .literalblock pre {
-  background: var(--atom-one-dark-bg, #282c34);
+html.dark .boostlook .doc .literalblock pre,
+html.dark .boostlook#libraryReadMe > pre:not(:last-child),
+html.dark .boostlook#libraryReadMe div.highlight:has(> pre):not(:is(dd pre, td pre)),
+html.dark .boostlook .doc .literalblock pre,
+html.dark .boostlook .literalblock pre,
+html.dark .boostlook .literalblock > .content > pre:not(.highlight),
+html.dark .boostlook .listingblock > .content > pre,
+html.dark .boostlook .sidebarblock,
+html.dark .boostlook .exampleblock > .content,
+html.dark .boostlook .listingblock > .content > pre {
+  background: var(--atom-one-dark-bg, #282c34) !important;
 }

 .boostlook .doc pre {
@@ -1478,8 +1528,10 @@ html.dark .boostlook .doc .literalblock pre {
 }

 .boostlook .highlight pre,
-.boostlook .content:has(> pre) pre.highlight {
+.boostlook .content:has(> pre) pre.highlight,
+.boostlook .literalblock > .content > pre:not(.highlight) {
  border: 1px solid var(--border-border-secondary, #d5d7d9);
+  border-radius: 0;
 }
 .boostlook .content:has(> pre):has(> .source-toolbox) pre {
  /*border: 1px solid var(--border-border-secondary, #d5d7d9);*/
@@ -1759,12 +1811,14 @@ html.dark .boostlook .doc .literalblock pre {
 .boostlook pre span.sh,
 .boostlook pre span.comment,
 .boostlook .hljs-comment,
+.boostlook .cpp-comment,
 .boostlook .hljs-quote,
 .boostlook .hljs-addition,
 .boostlook .hljs-built_in,
 .boostlook .hljs-bullet,
 .boostlook .hljs-code {
  color: var(--atom-one-light-comment, #a0a1a7);
+  font-family: "Monaspace Xenon", monospace;
  font-style: italic;
 }

@@ -1780,12 +1834,15 @@ html.dark .boostlook pre span.sd,
 html.dark .boostlook pre span.sh,
 html.dark .boostlook pre span.comment,
 html.dark .boostlook .hljs-comment,
+html.dark .boostlook .cpp-comment,
 html.dark .boostlook .hljs-quote,
 html.dark .boostlook .hljs-addition,
 html.dark .boostlook .hljs-built_in,
 html.dark .boostlook .hljs-bullet,
 html.dark .boostlook .hljs-code {
  color: var(--atom-one-dark-comment, #5c6370);
+  font-family: "Monaspace Xenon", monospace;
+  font-style: italic;
 }

 .boostlook pre span.s,
@@ -1888,6 +1945,8 @@ html.dark .boostlook .hljs-code {
 .boostlook .doc .verseblock blockquote,
 .boostlook div.blockquote blockquote {
  margin: 0;
+  font: inherit;
+  color: inherit;
 }

 .boostlook .quoteblock blockquote .paragraph,
@@ -1907,6 +1966,10 @@ html.dark .boostlook .hljs-code {
  color: inherit;
 }

+.boostlook .quoteblock blockquote:before {
+  content: none;
+}
+
 /* Pagination */
 .boostlook nav.pagination {
  border-top: revert;
@@ -2209,7 +2272,7 @@ html.dark .boostlook .hljs-code {
 .boostlook:not(:has(.doc)) div.tip,
 .boostlook:not(:has(.doc)) .notices.tip {
  border-color: var(--border-border-positive, #f8fefb);
-  background-color: var(--colors-positive-0, rgba(240, 254, 247, 0.5));
+  background-color: var(--surface-background-states-surface-positive-primary, #f6fafd);
 }
 /* .boostlook #content .admonitionblock.tip > table tr td.icon,
 .boostlook:not(:has(.doc)) div.tip > table tr:first-child th,
@@ -2365,7 +2428,7 @@ html.dark .boostlook .hljs-code {
 .boostlook .dlist dl dt code,
 .boostlook:not(:has(.doc)) .variablelist dl dt code {
  font-variation-settings: "wght" 600, "wdth" 80;
-  font-family: var(--font-family-code, 'Noto Sans Mono');
+  font-family: var(--font-family-code, 'Monaspace Neon');
 }

 .boostlook .dlist dl dd,
@@ -3164,6 +3227,7 @@ html:has(#docsiframe)::-webkit-scrollbar {
 /* TOC Scrolling */
 .boostlook #toc.toc2 {
  overflow-y: auto;
+  scrollbar-color: inherit;
 }
 /* TOC Positioning */
 .boostlook #toc.toc2,
@@ -3486,6 +3550,7 @@ html.is-clipped--nav:has(.boostlook) div#content {
 .boostlook pre.rouge .c1,
 .boostlook pre.rouge .cm { /* Comments */
  color: var(--atom-one-light-comment, #a0a1a7);
+  font-family: "Monaspace Xenon", monospace;
  font-style: italic;
 }

@@ -3517,6 +3582,7 @@ html.dark .boostlook pre.rouge .c,
 html.dark .boostlook pre.rouge .c1,
 html.dark .boostlook pre.rouge .cm {
  color: var(--atom-one-dark-comment, #5c6370);
+  font-family: "Monaspace Xenon", monospace;
  font-style: italic;
 }

@@ -3937,6 +4003,209 @@ html.dark .boostlook pre.rouge .cm {
  background-color: transparent;
 }

+/* Search Field Container */
+#search-field {
+  display: flex;
+  position: relative;
+}
+
+/* Search Input */
+#search-input {
+  padding: 0.15rem 0.75rem 0.15rem 1.75rem !important;
+  border: 1px solid var(--border-border-secondary);
+  border-radius: 6px;
+  background-color: var(--surface-background-main-surface-primary);
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24' fill='none' stroke='%236b7280' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cpath d='m21 21-4.35-4.35'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: 0.35rem center;
+  background-size: 16px 16px;
+  color: var(--text-main-text-body-primary);
+  font-family: inherit;
+  font-size: 1rem !important; /* 16px minimum prevents iOS zoom on focus */
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+
+#search-input::placeholder {
+  color: var(--text-main-text-body-tetriary);
+}
+
+#search-input:focus {
+  outline: none;
+  border-color: var(--border-border-blue-primary);
+  box-shadow: 0 0 0 3px var(--colors-blue-50);
+}
+
+#search-input:disabled {
+  background: var(--colors-neutral-100);
+  color: var(--text-main-text-body-tetriary);
+  cursor: not-allowed;
+}
+
+/* Results Dropdown */
+.search-result-dropdown-menu {
+  position: absolute;
+  z-index: 100;
+  top: 100%;
+  right: 0;
+  margin-top: 8px;
+  min-width: 400px;
+  border-radius: 8px;
+  background: var(--surface-background-main-base-primary);
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
+}
+
+.search-result-dataset {
+  padding: 0.5rem;
+  border: 1px solid var(--border-border-secondary);
+  border-radius: 8px;
+  min-width: 580px;
+  max-height: calc(100vh - 6rem);
+  overflow: auto;
+}
+
+/* Result Component Header */
+.search-result-component-header {
+  padding: 0.5rem 0.75rem;
+  margin: 0.25rem 0;
+  border-bottom: 1px solid var(--border-border-secondary);
+  color: var(--text-main-text-body-secondary);
+  font-size: 0.75rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.025em;
+}
+
+/* Result Item */
+.search-result-item {
+  display: flex;
+  margin: 0.25rem 0;
+  border-radius: 6px;
+}
+
+.search-result-item:hover {
+  background: var(--colors-neutral-50);
+}
+
+.search-result-item .no-result {
+  padding: 1rem;
+  color: var(--text-main-text-body-tetriary);
+  text-align: center;
+}
+
+/* Result Document Title (Left Column) */
+.search-result-document-title {
+  width: 25%;
+  padding: 0.625rem 0.75rem;
+  border-right: 1px solid var(--border-border-secondary);
+  color: var(--text-main-text-body-tetriary);
+  font-size: 0.75rem;
+  text-align: right;
+}
+
+/* Result Document Hit (Right Column) */
+.search-result-document-hit {
+  flex: 1;
+  color: var(--text-main-text-body-secondary);
+  font-size: 0.8125rem;
+}
+
+.search-result-document-hit > a {
+  display: block;
+  padding: 0.5rem 0.75rem;
+  color: inherit;
+  text-decoration: none;
+}
+
+.search-result-document-hit > a:hover {
+  background: transparent;
+}
+
+.search-result-document-hit .search-result-section-title {
+  margin-bottom: 0.25rem;
+  color: var(--text-main-text-body-primary);
+  font-size: 0.875rem;
+  font-weight: 500;
+}
+
+.search-result-document-hit .search-result-highlight {
+  padding: 0.1em 0.2em;
+  border-radius: 2px;
+  background: var(--colors-blue-50);
+  color: var(--text-main-text-link-blue);
+  font-weight: 500;
+}
+
+/* Search Responsive: Mobile (< 768px) */
+@media screen and (max-width: 767px) {
+  .boostlook .toolbar {
+    flex-wrap: wrap;
+    gap: 0.75rem;
+  }
+
+  .search-container {
+    order: 99;
+    flex: 1 0 100%;
+  }
+
+  #search-input {
+    width: 100% !important;
+    min-width: unset;
+    font-size: 1rem !important; /* Prevents iOS zoom on focus */
+  }
+
+  .search-result-dropdown-menu {
+    position: fixed;
+    top: 6rem;
+    left: 1rem;
+    right: 1rem;
+    min-width: unset;
+    max-width: unset;
+    width: auto;
+  }
+
+  .search-result-dataset {
+    min-width: unset;
+  }
+}
+
+/* Search Responsive: Tablet (768px - 1023px) */
+@media screen and (min-width: 768px) {
+  #search-input {
+    width: unset !important;
+    min-width: unset !important;
+  }
+
+  .search-result-dropdown-menu {
+    position: fixed;
+    top: 4rem;
+    left: calc(var(--main-max-width-leftbar) + 1rem);
+    right: 1rem;
+    min-width: unset;
+    max-width: unset;
+    width: auto;
+  }
+
+  .search-result-dataset {
+    min-width: unset;
+  }
+}
+
+/* Search Responsive: Desktop (1024px+) */
+@media screen and (min-width: 1024px) {
+  #search-input {
+    min-width: 200px !important;
+    z-index: 1001;
+  }
+
+  .search-result-dropdown-menu {
+    position: absolute;
+    top: 100%;
+    left: auto;
+    right: 0;
+    width: clamp(530px, 45vw, 600px);
+  }
+}
+
 /*----------------- Styles specific to Antora Templates end -----------------*/

 /*---------- Quickbook docs styling fixes -----------*/
--- a/workflows/WORKFLOW.md
+++ b/workflows/WORKFLOW.md
@@ -0,0 +1,347 @@
+# Boostlook CSS Workflow Documentation
+
+This document describes the GitHub Actions workflow that synchronizes `boostlook.css` across the Boost documentation ecosystem. It covers how styling changes flow from this repository to the production websites.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Repository Relationships](#repository-relationships)
+- [Workflow Diagram](#workflow-diagram)
+- [Detailed Workflow Steps](#detailed-workflow-steps)
+- [Branch Strategy](#branch-strategy)
+- [Manual Triggers](#manual-triggers)
+- [Technical Reference](#technical-reference)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+The boostlook repository is the **single source of truth** for Boost's documentation styling. When `boostlook.css` is modified, automated workflows propagate those changes to two downstream repositories:
+
+1. **website-v2** - The main Boost website (Django-based)
+2. **website-v2-docs** - The Antora-based documentation site
+
+This ensures visual consistency across all Boost web properties.
+
+---
+
+## Repository Relationships
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              BOOSTLOOK                                      │
+│                    (boostorg/boostlook)                                     │
+│                                                                             │
+│  Source of truth for boostlook.css                                          │
+│  Branch: develop                                                            │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    │ On push to develop (boostlook.css changed)
+                                    │ OR manual workflow_dispatch
+                                    ▼
+        ┌───────────────────────────┴───────────────────────────┐
+        │                                                       │
+        ▼                                                       ▼
+┌───────────────────────────────┐       ┌───────────────────────────────────┐
+│         WEBSITE-V2            │       │         WEBSITE-V2-DOCS           │
+│    (boostorg/website-v2)      │       │    (boostorg/website-v2-docs)     │
+│                               │       │                                   │
+│  Receives: direct file copy   │       │  Receives: workflow trigger       │
+│  Location: static/css/        │       │  Process: fetches from boostlook  │
+│            boostlook.css      │       │           during antora-ui build  │
+│  Branch: develop              │       │  Branch: develop                  │
+│                               │       │                                   │
+│  Django website               │       │  Antora documentation site        │
+└───────────────────────────────┘       └───────────────────────────────────┘
+        │                                       │
+        │ actions-gcp.yaml                      │ publish.yml
+        ▼                                       ▼
+┌───────────────────────────────┐       ┌───────────────────────────────────┐
+│     GKE DEPLOYMENT            │       │     AWS S3 + FASTLY CDN           │
+│                               │       │                                   │
+│  develop → stage namespace    │       │  Documentation hosting            │
+│  master → production          │       │  with CDN caching                 │
+└───────────────────────────────┘       └───────────────────────────────────┘
+```
+
+---
+
+## Workflow Diagram
+
+### Sync Process Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  1. Developer pushes changes to boostlook.css on develop branch             │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  2. sync-boostlook-css.yml workflow triggers                                │
+│     - Checks out boostlook repo                                             │
+│     - Checks out website-v2 repo (develop branch)                           │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  3. Copy boostlook.css to website-v2/static/css/boostlook.css               │
+│     - Run pre-commit hooks for validation                                   │
+│     - Commit and push to website-v2 develop branch                          │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  4. Trigger website-v2-docs workflows:                                      │
+│     - ui-release.yml: Builds new Antora UI bundle                           │
+│     - publish.yml: Rebuilds and publishes documentation                     │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                    ┌───────────────┴───────────────┐
+                    ▼                               ▼
+┌───────────────────────────────┐   ┌───────────────────────────────────────┐
+│  5a. website-v2 deploys       │   │  5b. website-v2-docs deploys          │
+│      via actions-gcp.yaml     │   │      to AWS S3 + Fastly               │
+│      to GKE stage namespace   │   │                                       │
+└───────────────────────────────┘   └───────────────────────────────────────┘
+```
+
+---
+
+## Detailed Workflow Steps
+
+### Step 1: Trigger Conditions
+
+The `sync-boostlook-css.yml` workflow in this repository triggers when:
+
+| Trigger | Condition | Branch |
+|---------|-----------|--------|
+| Push | `boostlook.css` file is modified | `develop` |
+| Manual | `workflow_dispatch` from GitHub UI | Any (runs on develop) |
+
+**Important**: The workflow only runs when executed from the official `boostorg/boostlook` repository (fork protection).
+
+### Step 2: CSS Synchronization to website-v2
+
+The workflow performs these actions:
+
+1. **Checkout repositories**
+   - Checks out boostlook (current repo)
+   - Checks out `boostorg/website-v2` (develop branch) into `website-v2/` subdirectory
+
+2. **Copy CSS file**
+   ```
+   boostlook.css → website-v2/static/css/boostlook.css
+   ```
+
+3. **Validation**
+   - Installs pre-commit
+   - Runs pre-commit hooks on the copied CSS file
+
+4. **Commit and push**
+   - Commits with message: `chore: Update boostlook.css from boostlook repository`
+   - Pushes to website-v2's develop branch
+   - Skips if no changes detected
+
+### Step 3: Trigger website-v2-docs Workflows
+
+After successfully updating website-v2, the workflow triggers two workflows in `boostorg/website-v2-docs`:
+
+#### ui-release.yml
+
+Builds the Antora UI bundle:
+
+1. Sets up Node.js 18.x
+2. Runs `npm ci` and `gulp bundle` in the `antora-ui` directory
+3. The gulp build process **fetches boostlook.css** from this repository:
+   ```
+   https://raw.githubusercontent.com/boostorg/boostlook/${BOOSTLOOK_BRANCH}/boostlook.css
+   ```
+4. Creates a GitHub release tagged `ui-{branch-name}` with `ui-bundle.zip`
+
+**Note**: The `BOOSTLOOK_BRANCH` environment variable determines which branch to fetch from. In CI, this defaults to `develop` unless the current branch is `master`.
+
+#### publish.yml
+
+Builds and deploys the documentation:
+
+1. Runs `build.sh` to generate documentation
+2. Syncs to AWS S3 (multiple environments)
+3. Purges Fastly CDN cache
+
+### Step 4: Downstream Deployments
+
+#### website-v2 Deployment
+
+The `actions-gcp.yaml` workflow in website-v2 handles deployment:
+
+| Branch | Deployment Target |
+|--------|-------------------|
+| `develop` | GKE `stage` namespace |
+| `master` | GKE `production` namespace |
+
+#### website-v2-docs Deployment
+
+The `publish.yml` workflow deploys to:
+- AWS S3 buckets (multiple environments)
+- Fastly CDN with cache purging
+
+---
+
+## Branch Strategy
+
+### Current Configuration
+
+| Repository | Development Branch | Production Branch |
+|------------|-------------------|-------------------|
+| boostlook | `develop` | `master` |
+| website-v2 | `develop` | `master` |
+| website-v2-docs | `develop` | `master` |
+
+### How Changes Flow
+
+```
+boostlook (develop) ──► website-v2 (develop) ──► Stage deployment
+                   └──► website-v2-docs (develop) ──► Stage documentation
+
+boostlook (master) ──► Manual process or separate workflow for production
+```
+
+**Current Behavior**: The automated sync workflow only operates on the `develop` branch. Production deployments follow a separate process (typically merging develop to master).
+
+### Recommended Workflow
+
+1. Make CSS changes in boostlook on `develop` branch
+2. Changes automatically sync to staging environments
+3. Test changes on staging
+4. Merge `develop` to `master` in all three repos for production
+
+---
+
+## Manual Triggers
+
+### Triggering the Sync Workflow Manually
+
+1. Go to **Actions** tab in the boostlook repository
+2. Select **"Sync boostlook.css to website-v2 & website-v2-docs"**
+3. Click **"Run workflow"**
+4. Select the branch (typically `develop`)
+5. Click **"Run workflow"**
+
+### When to Use Manual Triggers
+
+- After fixing a failed automatic sync
+- To force a refresh without changing the CSS
+- Testing workflow changes
+- Recovering from sync issues
+
+---
+
+## Technical Reference
+
+### Files Involved
+
+| Repository | File | Purpose |
+|------------|------|---------|
+| boostlook | `.github/workflows/sync-boostlook-css.yml` | Main sync workflow |
+| boostlook | `boostlook.css` | Source stylesheet |
+| website-v2 | `static/css/boostlook.css` | Destination (Django static) |
+| website-v2 | `.github/workflows/actions-gcp.yaml` | GKE deployment |
+| website-v2-docs | `.github/workflows/ui-release.yml` | Antora UI bundle build |
+| website-v2-docs | `.github/workflows/publish.yml` | Documentation publish |
+| website-v2-docs | `antora-ui/gulp.d/tasks/build.js` | Fetches boostlook.css |
+
+### Required Secrets
+
+The sync workflow requires these GitHub secrets:
+
+| Secret | Purpose |
+|--------|---------|
+| `WEBSITE_V2_PAT` | Personal Access Token with write access to website-v2 and website-v2-docs repositories |
+
+### Environment Variables
+
+| Variable | Used In | Default | Purpose |
+|----------|---------|---------|---------|
+| `BOOSTLOOK_BRANCH` | website-v2-docs | `master` (CI: `develop`) | Branch to fetch boostlook.css from |
+
+### API Endpoints
+
+The antora-ui build fetches boostlook.css from:
+```
+https://raw.githubusercontent.com/boostorg/boostlook/${BOOSTLOOK_BRANCH}/boostlook.css
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### Sync workflow failed at "Commit and push"
+
+**Cause**: The `WEBSITE_V2_PAT` token may have expired or lack permissions.
+
+**Solution**:
+1. Generate a new PAT with `repo` scope
+2. Update the `WEBSITE_V2_PAT` secret in boostlook repository settings
+
+#### Changes not appearing on staging
+
+**Possible causes**:
+1. Workflow failed silently
+2. CDN cache not purged
+3. Downstream workflow failed
+
+**Solution**:
+1. Check Actions tab in all three repositories
+2. Manually trigger CDN purge
+3. Re-run failed workflows
+
+#### website-v2-docs showing old styles
+
+**Cause**: The antora-ui build may be using cached boostlook.css.
+
+**Solution**:
+1. Check the `BOOSTLOOK_BRANCH` variable
+2. Manually trigger ui-release.yml with `--skip-boostlook` disabled
+3. Verify the CSS URL is accessible
+
+#### Pre-commit hooks failing
+
+**Cause**: CSS formatting issues.
+
+**Solution**:
+1. Run pre-commit locally: `pre-commit run --files boostlook.css`
+2. Fix any reported issues
+3. Push the corrected file
+
+### Verification Steps
+
+After making changes, verify the sync worked:
+
+1. **Check workflow status**: Actions tab in boostlook repo
+2. **Verify website-v2 commit**: Check recent commits on develop branch
+3. **Check ui-release.yml**: Actions tab in website-v2-docs
+4. **Check publish.yml**: Actions tab in website-v2-docs
+5. **Test staging sites**: Verify CSS changes are visible
+
+### Logs and Debugging
+
+Each workflow step outputs logs accessible from the Actions tab. Key logs to check:
+
+- `Copy boostlook.css to website-v2` - Confirms file was copied
+- `Commit and push changes` - Shows if changes were detected
+- `Trigger website-v2-docs ui-release workflow` - Confirms downstream trigger
+
+---
+
+## Additional Resources
+
+- [website-v2-operations Deployments](https://github.com/cppalliance/website-v2-operations/tree/master/deployments) - Infrastructure documentation
+- [Antora UI README](https://github.com/boostorg/website-v2-docs/tree/develop/antora-ui) - UI bundle documentation
+- [Boost.Build Documentation](https://boostorg.github.io/build/) - For local preview setup
+
+---
+
+*Last updated: January 2025*
Author	SHA1	Message	Date
Claude	1be9930ede	docs: add workflow documentation for CSS sync process Document the GitHub Actions workflow that synchronizes boostlook.css across boostlook, website-v2, and website-v2-docs repositories. Includes high-level overview, detailed technical reference, branch strategy, and troubleshooting guide. https://claude.ai/code/session_01E9Mz7zZRPiVNn234U4dbXa	2026-01-26 19:13:07 +00:00
Julio Estrada	373ad4649e	feat: add search input and results dropdown styling (#142 ) - Search input with inline SVG icon - Responsive dropdown positioning for mobile, tablet, and desktop - Mobile layout with full-width search on second row	2026-01-16 02:49:40 -05:00
Julio Estrada	edfeff5eea	fix: improve text legibility (#569 ) - Fix CSS selector syntax (missing commas in dark theme rules) - Correct positive-primary color hex code (#f6fafd -> #f0fef7) - Adjust background colors for light and dark themes - Remove borders and shadows from code blocks - Update sidebar margins and borders for better layout - Refine blockquote styles for consistency	2025-12-28 07:07:37 -05:00
Julio Estrada	f056e064ea	refactor: streamline font URLs, remove comments - Streamline font source URLs in @font-face declarations - Remove unnecessary comments	2025-12-18 16:31:19 -05:00
Julio Estrada	d264e70b57	fix: enable contextual alternates in code blocks	2025-12-16 14:32:25 -05:00
Julio Estrada	858f832cf5	fix: add cpp-comment class styling support	2025-12-11 18:02:08 -05:00
Julio Estrada	6adfbca7ab	fix: disable ligatures in code blocks	2025-12-11 17:55:35 -05:00
Julio Estrada	db04621383	feat: update to Monaspace variable fonts	2025-12-10 21:46:16 -05:00
Julio Estrada	dec44ce10a	fix: adjust font feature settings	2025-12-10 19:50:44 -05:00
Julio Estrada	ab2d0fda0a	feat: enhance code styling with font feature settings for improved typography	2025-12-10 18:19:57 -05:00
Julio Estrada	8c9f0364d1	refactor: remove Monaspace Radon font references and update to Monaspace Xenon	2025-12-10 16:54:46 -05:00
Julio Estrada	e32c8bda45	feat: update font to Monaspace Xenon Italic	2025-12-10 16:10:38 -05:00
Julio Estrada	76d10265f5	add comment styling with Monaspace Radon font	2025-12-10 01:47:39 -05:00
Julio Estrada	2afbebc0c5	feat: add Monaspace Radon Italic font	2025-12-10 01:25:05 -05:00
Julio Estrada	d0cc6d5e1e	refactor: update monospaced font to Monaspace Neon	2025-12-09 18:19:09 -05:00
Julio Estrada	20ddde5333	fix: update workflow dependencies - Upgrade actions/checkout from v4 to v6 - Upgrade Python from 3.11 to 3.13	2025-11-20 18:40:00 -05:00
Julio Estrada	66401ab4d7	fix: change font-display swap to block Prevent FOUT by blocking text render until fonts load	2025-11-20 14:31:37 -05:00
Julio Estrada	cdfdff1a43	Prioritize local fonts for antora bundles Add local font paths first in @font-face src to check for fonts in antora-bundled projects before remote fallbacks. Required before boostorg/website-v2-docs#545 can merge.	2025-11-19 23:27:51 -05:00
Julio Estrada	c8ea8e2061	fix foit: swap, fallbacks, metric overrides (#145 ) - use font-display: swap to avoid invisible text - add system fallbacks for body/code stacks - add size-adjust/ascent/descent/line-gap to reduce cls refs: issue #145	2025-09-29 16:45:47 -04:00
Julio Estrada	5454b1c038	remove visited link color overrides	2025-09-16 14:34:52 -04:00
Julio Estrada	34fb6a94b3	fix: update font source to noto sans italic	2025-09-13 18:30:00 -04:00
Julio Estrada	b4306e4b94	Fix dark mode background for library readme	2025-07-18 12:39:16 -04:00
Tino	36d2ef80b0	Changed the font-variation-settings value for .boostlook .doc .conum[data-value] to "wght" 350, "wdth" 80	2025-07-07 12:05:53 -04:00