From 7cc9584d71e52e3d64ed0a506ec7e2d002744674 Mon Sep 17 00:00:00 2001 From: taitelee Date: Fri, 3 Jul 2026 12:27:14 -0400 Subject: [PATCH 1/8] feat(docs): override Starlight header with a top-level site nav --- docs/astro.config.mjs | 1 + docs/src/components/Header.astro | 143 +++++++++++++++++++++++++++++++ docs/src/config/sidebar.ts | 13 +++ docs/src/env.d.ts | 24 +++++- 4 files changed, 179 insertions(+), 2 deletions(-) create mode 100644 docs/src/components/Header.astro diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index b9b71ad1..afe007bc 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -146,6 +146,7 @@ export default defineConfig({ }, }, components: { + Header: "./src/components/Header.astro", Hero: "./src/components/Hero.astro", SiteTitle: "./src/components/SiteTitle.astro", Footer: "./src/components/Footer.astro", diff --git a/docs/src/components/Header.astro b/docs/src/components/Header.astro new file mode 100644 index 00000000..abd682bf --- /dev/null +++ b/docs/src/components/Header.astro @@ -0,0 +1,143 @@ +--- +// Override of Starlight's default Header — a faithful copy plus a site-nav +// column. We override the whole Header (rather than stuffing links into +// SiteTitle, whose .title-wrapper has `overflow: clip`) so the nav can be its +// own grid item; every other control stays wired through its +// `virtual:starlight/components/*` import, so the SiteTitle/Search/Theme +// overrides and the Pagefind-search logic keep working untouched. The outer +//
(PageFrame — fixed position + glass background) is +// not ours and stays as-is. +// +// On @astrojs/starlight upgrades, re-diff this file against the upstream +// default Header: the layout markup and CSS here are a copy and can drift +// when Starlight changes its own Header internals. +// +// The nav is hidden below Starlight's `md` (50rem): on doc pages the sidebar +// (a hamburger drawer under 50rem) already carries navigation, so this fills +// the one real gap — the splash homepage, which hides the sidebar — on desktop. +import config from "virtual:starlight/user-config"; + +import LanguageSelect from "virtual:starlight/components/LanguageSelect"; +import Search from "virtual:starlight/components/Search"; +import SiteTitle from "virtual:starlight/components/SiteTitle"; +import SocialIcons from "virtual:starlight/components/SocialIcons"; +import ThemeSelect from "virtual:starlight/components/ThemeSelect"; +import { headerNav } from "../config/sidebar.ts"; + +// Mirror of the package default: only render Search when Pagefind is enabled or +// the Search component has been overridden. +const shouldRenderSearch = + config.pagefind || + config.components.Search !== "@astrojs/starlight/components/Search.astro"; + +// Highlight the active destination. trailingSlash is "never", so a trailing +// slash shouldn't appear — strip a stray one before comparing, just in case. +const currentPath = Astro.url.pathname.replace(/(.)\/$/, "$1"); +--- + +
+
+ +
+ +
+ {shouldRenderSearch && } +
+
+ + + +
+
+ + diff --git a/docs/src/config/sidebar.ts b/docs/src/config/sidebar.ts index ab113d2a..a7c0bf12 100644 --- a/docs/src/config/sidebar.ts +++ b/docs/src/config/sidebar.ts @@ -83,3 +83,16 @@ export const sidebar: StarlightUserConfig["sidebar"] = [ ], }, ]; + +// Curated top-level destinations for the site header (src/components/Header.astro). +// A deliberately small subset of the sidebar above — the sidebar still carries +// the full tree — colocated here so header and sidebar share one file as the +// single source of truth for navigation. Root-absolute hrefs match the internal +// link convention used across the docs (index.mdx hero, LinkCards). +export const headerNav: { label: string; href: string }[] = [ + { label: "Getting Started", href: "/getting-started" }, + { label: "Why WaveHouse?", href: "/why-wavehouse" }, + { label: "Architecture", href: "/architecture" }, + { label: "API", href: "/api" }, + { label: "SDK", href: "/sdk" }, +]; diff --git a/docs/src/env.d.ts b/docs/src/env.d.ts index 740490d2..d5372f61 100644 --- a/docs/src/env.d.ts +++ b/docs/src/env.d.ts @@ -3,8 +3,8 @@ // Starlight exposes its built-in components to overrides through these virtual // modules (Vite resolves them at build time), but only ships their TYPES in an // internal declaration file that isn't visible to user code — so `astro check` -// can't find them. Declare the ones the Footer override re-renders. See -// node_modules/@astrojs/starlight/virtual-internal.d.ts for the canonical list. +// can't find them. Declare the ones the Footer and Header overrides re-render. +// See node_modules/@astrojs/starlight/virtual-internal.d.ts for the canonical list. declare module "virtual:starlight/components/EditLink" { const Component: import("astro").AstroComponentFactory; export default Component; @@ -17,3 +17,23 @@ declare module "virtual:starlight/components/Pagination" { const Component: import("astro").AstroComponentFactory; export default Component; } +declare module "virtual:starlight/components/LanguageSelect" { + const Component: import("astro").AstroComponentFactory; + export default Component; +} +declare module "virtual:starlight/components/Search" { + const Component: import("astro").AstroComponentFactory; + export default Component; +} +declare module "virtual:starlight/components/SiteTitle" { + const Component: import("astro").AstroComponentFactory; + export default Component; +} +declare module "virtual:starlight/components/SocialIcons" { + const Component: import("astro").AstroComponentFactory; + export default Component; +} +declare module "virtual:starlight/components/ThemeSelect" { + const Component: import("astro").AstroComponentFactory; + export default Component; +} From 7c86cc0c9c986cd7cdfb1eb0f779b98ba0c9cb9a Mon Sep 17 00:00:00 2001 From: taitelee Date: Fri, 3 Jul 2026 13:21:20 -0400 Subject: [PATCH 2/8] fix(docs): reduce header nav to a single Docs link and align the logomark to the text baseline --- docs/src/components/SiteTitle.astro | 14 ++++++++++++++ docs/src/config/sidebar.ts | 17 +++++++---------- 2 files changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/src/components/SiteTitle.astro b/docs/src/components/SiteTitle.astro index 3b51f881..ee8d3ad6 100644 --- a/docs/src/components/SiteTitle.astro +++ b/docs/src/components/SiteTitle.astro @@ -43,6 +43,20 @@ const title = color 0.15s ease; } + /* Once the wordmark sits beside it (>30rem), the mark is taller than the + text, so centering leaves its bottom dipping below the baseline. Nudge it + up — visual only, no layout shift, so the wordmark and header nav stay put + — to sit its bottom on the shared text baseline (value optically tuned). + At <=30rem only the mark shows, so it stays centered with no nudge. */ + @media (min-width: 30.0625rem) { + .wh-site-title__mark { + transform: translateY(-0.25rem); + } + .wh-site-title:hover .wh-site-title__mark { + transform: translateY(-0.25rem) rotate(-2deg); + } + } + @media (max-width: 30rem) { .wh-site-title__text { display: none; diff --git a/docs/src/config/sidebar.ts b/docs/src/config/sidebar.ts index a7c0bf12..22c041ae 100644 --- a/docs/src/config/sidebar.ts +++ b/docs/src/config/sidebar.ts @@ -84,15 +84,12 @@ export const sidebar: StarlightUserConfig["sidebar"] = [ }, ]; -// Curated top-level destinations for the site header (src/components/Header.astro). -// A deliberately small subset of the sidebar above — the sidebar still carries -// the full tree — colocated here so header and sidebar share one file as the -// single source of truth for navigation. Root-absolute hrefs match the internal -// link convention used across the docs (index.mdx hero, LinkCards). +// Top-level link(s) for the site header (src/components/Header.astro), colocated +// with the sidebar so header and sidebar share one file as the single source of +// truth for navigation. A single "Docs" entry into the doc tree: the splash +// homepage hides the sidebar, so this is the way in from there; every doc page +// already carries the full sidebar. Root-absolute href matches the internal link +// convention used across the docs (index.mdx hero, LinkCards). export const headerNav: { label: string; href: string }[] = [ - { label: "Getting Started", href: "/getting-started" }, - { label: "Why WaveHouse?", href: "/why-wavehouse" }, - { label: "Architecture", href: "/architecture" }, - { label: "API", href: "/api" }, - { label: "SDK", href: "/sdk" }, + { label: "Docs", href: "/getting-started" }, ]; From 4b304fc3c2391d53657fefb3ee2320ed5e573d91 Mon Sep 17 00:00:00 2001 From: taitelee Date: Fri, 3 Jul 2026 14:56:33 -0400 Subject: [PATCH 3/8] =?UTF-8?q?feat(docs):=20redesign=20header=20=E2=80=94?= =?UTF-8?q?=20centered=20splash=20/=20full-width=20docs,=20compact/expande?= =?UTF-8?q?d=20search,=20Get=20Started=20CTA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/src/components/Header.astro | 234 +++++++++++++++++++--------- docs/src/components/SiteTitle.astro | 14 -- 2 files changed, 164 insertions(+), 84 deletions(-) diff --git a/docs/src/components/Header.astro b/docs/src/components/Header.astro index abd682bf..91ca8e18 100644 --- a/docs/src/components/Header.astro +++ b/docs/src/components/Header.astro @@ -1,20 +1,22 @@ --- -// Override of Starlight's default Header — a faithful copy plus a site-nav -// column. We override the whole Header (rather than stuffing links into -// SiteTitle, whose .title-wrapper has `overflow: clip`) so the nav can be its -// own grid item; every other control stays wired through its -// `virtual:starlight/components/*` import, so the SiteTitle/Search/Theme -// overrides and the Pagefind-search logic keep working untouched. The outer -//
(PageFrame — fixed position + glass background) is -// not ours and stays as-is. +// Custom header overriding Starlight's default. The layout is our own — its +// contents are held in a centered max-width column (matching the page content, +// à la ClickHouse/Supabase) rather than spanning edge to edge: brand + primary +// nav pinned left, controls + a "Get Started" call-to-action pinned right, with +// a compact icon search among the right-hand controls. Every control is still +// Starlight's own built-in, pulled in through its `virtual:starlight/components/*` +// import, so the SiteTitle/Search/Theme overrides and the Pagefind-search logic +// keep working untouched. The outer
(PageFrame — fixed +// position + full-width glass background) is not ours and stays as-is; only our +// inner content is column-constrained, so the bar itself still spans the page. // -// On @astrojs/starlight upgrades, re-diff this file against the upstream -// default Header: the layout markup and CSS here are a copy and can drift -// when Starlight changes its own Header internals. +// Because the controls are Starlight built-ins re-rendered here, env.d.ts +// declares their virtual modules so `astro check` can resolve them. On +// @astrojs/starlight upgrades, re-check those component module paths. // -// The nav is hidden below Starlight's `md` (50rem): on doc pages the sidebar -// (a hamburger drawer under 50rem) already carries navigation, so this fills -// the one real gap — the splash homepage, which hides the sidebar — on desktop. +// The left nav and the controls/CTA are hidden below Starlight's `md` (50rem): +// under 50rem the sidebar (a hamburger drawer) already carries navigation on +// doc pages, leaving the logo + the (always-visible) search button. import config from "virtual:starlight/user-config"; import LanguageSelect from "virtual:starlight/components/LanguageSelect"; @@ -30,80 +32,161 @@ const shouldRenderSearch = config.pagefind || config.components.Search !== "@astrojs/starlight/components/Search.astro"; -// Highlight the active destination. trailingSlash is "never", so a trailing -// slash shouldn't appear — strip a stray one before comparing, just in case. +// Highlight the active destination — exact match, or any nested page beneath it +// (so a "/guides" link stays current on "/guides/foo"). trailingSlash is +// "never", so strip a stray trailing slash before comparing, just in case. const currentPath = Astro.url.pathname.replace(/(.)\/$/, "$1"); + +// Primary call-to-action. Points at the docs entry point for now; repoint if a +// dedicated quickstart/install page lands. +const ctaHref = "/getting-started"; ---
-
- +
+
+ +
+
- -
- {shouldRenderSearch && } -
-
-
diff --git a/docs/src/components/SiteTitle.astro b/docs/src/components/SiteTitle.astro index ee8d3ad6..3b51f881 100644 --- a/docs/src/components/SiteTitle.astro +++ b/docs/src/components/SiteTitle.astro @@ -43,20 +43,6 @@ const title = color 0.15s ease; } - /* Once the wordmark sits beside it (>30rem), the mark is taller than the - text, so centering leaves its bottom dipping below the baseline. Nudge it - up — visual only, no layout shift, so the wordmark and header nav stay put - — to sit its bottom on the shared text baseline (value optically tuned). - At <=30rem only the mark shows, so it stays centered with no nudge. */ - @media (min-width: 30.0625rem) { - .wh-site-title__mark { - transform: translateY(-0.25rem); - } - .wh-site-title:hover .wh-site-title__mark { - transform: translateY(-0.25rem) rotate(-2deg); - } - } - @media (max-width: 30rem) { .wh-site-title__text { display: none; From 518e35e21e18ddae90bf7b7f65dd1610a7386b3a Mon Sep 17 00:00:00 2001 From: taitelee Date: Fri, 3 Jul 2026 15:14:24 -0400 Subject: [PATCH 4/8] fix(docs): gate expanded header search to >=50rem to avoid mobile overflow --- docs/src/components/Header.astro | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/src/components/Header.astro b/docs/src/components/Header.astro index 91ca8e18..44509051 100644 --- a/docs/src/components/Header.astro +++ b/docs/src/components/Header.astro @@ -151,20 +151,29 @@ const ctaHref = "/getting-started"; border-inline-end: 1px solid var(--sl-color-gray-5); } - /* Search: collapse Starlight's search box to a compact icon button (the - "Search" label + ⌘K hint are already `md:`-only, so hide them at every - width) that opens the same modal, ClickHouse-style. */ + /* Search. Doc pages show Starlight's expanded "Search … ⌘K" box; the splash + homepage collapses it to a compact icon. Either way it opens the same + modal. */ .wh-search { align-items: center; } - /* Doc pages: keep Starlight's expanded search box, sized to a comfortable - width. */ - .wh-search :global(button[data-open-modal]) { - width: 22rem; - max-width: 100%; + /* Expand to the box only from 50rem up — the same breakpoint that reveals the + controls. Below it the label + ⌘K are already hidden (md:-only), so forcing + a width would leave a wide, near-empty button overflowing the narrow header + beside the logo; letting it size to its icon keeps it compact there. + min-width:0 + max-width let it shrink rather than overflow if the desktop + row gets tight. */ + @media (min-width: 50rem) { + .wh-search { + min-width: 0; + } + .wh-search :global(button[data-open-modal]) { + width: 22rem; + max-width: 100%; + } } - /* Splash: collapse to a compact icon button (its "Search" label + ⌘K hint - are already md-only) that opens the same modal, ClickHouse-style. */ + /* Splash homepage: collapse to a compact icon button at every width (label + + ⌘K hidden), ClickHouse-style. */ :global(body:has(.wh-hero)) .wh-search :global(button[data-open-modal] > span), :global(body:has(.wh-hero)) .wh-search :global(button[data-open-modal] > kbd) { display: none; From 35ee725549d81409b1b2b269b1b8ad2bc4b2c937 Mon Sep 17 00:00:00 2001 From: taitelee Date: Fri, 3 Jul 2026 15:27:36 -0400 Subject: [PATCH 5/8] style(docs): size the header nav link smaller than the WaveHouse wordmark --- docs/src/components/Header.astro | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/src/components/Header.astro b/docs/src/components/Header.astro index 44509051..3441663c 100644 --- a/docs/src/components/Header.astro +++ b/docs/src/components/Header.astro @@ -192,10 +192,11 @@ const ctaHref = "/getting-started"; } .wh-header-nav__link { color: var(--wh-ink-muted); - /* Match the wordmark's font-size so, centered on the same header line, the - link's baseline lands exactly on the "WaveHouse" text baseline (the logo - itself is untouched — this only sizes the nav link). */ - font-size: 1.0625rem; + /* Smaller than the "WaveHouse" wordmark (1.0625rem). Both are centered on + the same header line, so the shorter link would otherwise sit slightly + high; drop it by half the size gap to land its bottom on the wordmark's. */ + font-size: 0.875rem; + transform: translateY(calc((1.0625rem - 0.875rem) / 2)); font-weight: 500; line-height: 1; text-decoration: none; From 30b273924f4316abc12bb8dbad034d0699b5e496 Mon Sep 17 00:00:00 2001 From: taitelee Date: Mon, 6 Jul 2026 11:23:55 -0400 Subject: [PATCH 6/8] refactor(docs): remove the Get Started CTA from the site header --- docs/src/components/Header.astro | 43 ++------------------------------ 1 file changed, 2 insertions(+), 41 deletions(-) diff --git a/docs/src/components/Header.astro b/docs/src/components/Header.astro index 3441663c..8570d7f3 100644 --- a/docs/src/components/Header.astro +++ b/docs/src/components/Header.astro @@ -2,8 +2,8 @@ // Custom header overriding Starlight's default. The layout is our own — its // contents are held in a centered max-width column (matching the page content, // à la ClickHouse/Supabase) rather than spanning edge to edge: brand + primary -// nav pinned left, controls + a "Get Started" call-to-action pinned right, with -// a compact icon search among the right-hand controls. Every control is still +// nav pinned left, controls pinned right, with a compact icon search among the +// right-hand controls. Every control is still // Starlight's own built-in, pulled in through its `virtual:starlight/components/*` // import, so the SiteTitle/Search/Theme overrides and the Pagefind-search logic // keep working untouched. The outer
(PageFrame — fixed @@ -36,10 +36,6 @@ const shouldRenderSearch = // (so a "/guides" link stays current on "/guides/foo"). trailingSlash is // "never", so strip a stray trailing slash before comparing, just in case. const currentPath = Astro.url.pathname.replace(/(.)\/$/, "$1"); - -// Primary call-to-action. Points at the docs entry point for now; repoint if a -// dedicated quickstart/install page lands. -const ctaHref = "/getting-started"; ---
@@ -83,7 +79,6 @@ const ctaHref = "/getting-started";
- Get Started
@@ -210,38 +205,4 @@ const ctaHref = "/getting-started"; color: var(--wh-accent-text); font-weight: 600; } - - /* Get Started CTA — the filled accent button that anchors the right side, - the way ClickHouse/Supabase headers do. */ - .wh-cta { - align-items: center; - padding: 0.45rem 0.95rem; - border-radius: 0.5rem; - background: var(--wh-accent); - color: var(--wh-cta-fg, #fff); - font-size: 0.9375rem; - font-weight: 600; - line-height: 1; - text-decoration: none; - white-space: nowrap; - transition: transform 0.15s ease, box-shadow 0.15s ease; - } - /* Hover: lift + accent-tinted shadow, keeping the fill constant so the - text/background contrast never changes on interaction. */ - .wh-cta:hover { - transform: translateY(-1px); - box-shadow: 0 4px 14px -4px var(--wh-accent); - } - /* In dark theme --wh-accent resolves to a bright cyan; white text on it - fails contrast (~2.6:1), so switch to dark ink. Covers both explicit dark - (data-theme) and auto/OS dark (prefers-color-scheme), matching how - Starlight itself themes. */ - :global([data-theme="dark"]) .wh-cta { - --wh-cta-fg: #052a30; - } - @media (prefers-color-scheme: dark) { - :global(:root:not([data-theme="light"])) .wh-cta { - --wh-cta-fg: #052a30; - } - } From add31c39b0907fb6eb7da47c03f9b276773f83ee Mon Sep 17 00:00:00 2001 From: taitelee Date: Mon, 6 Jul 2026 13:27:50 -0400 Subject: [PATCH 7/8] fix(docs): expand splash search, align and restyle the header Docs link --- CHANGELOG.md | 2 + docs/src/components/Header.astro | 72 +++++++++++++++----------------- 2 files changed, 35 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 07825cf9..7c389e98 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Mermaid diagrams export as PNG, with Copy/Download in the zoom lightbox** (`docs/src/integrations/diagram-png.mjs` (new), `docs/src/components/MermaidZoom.astro`, `docs/astro.config.mjs`, `docs/src/content/docs/development.md`): diagrams render as inline SVG (great for reading — selectable text, screen-reader semantics, theme-reactive colors) but can't be right-click-copied or dropped into a slide deck. A new `astro:build:done` integration now also rasterizes every diagram to `dist/diagrams//-[-transparent].png` — light **and** dark, 2× DPI, in two variants per theme (a WYSIWYG surface card and a transparent-background version for slide decks) — reusing the Playwright Chromium `rehype-mermaid` already needs, with a content-hash cache (`node_modules/.cache/wh-diagram-png`) so unchanged diagrams skip Chromium and the whole pass is wrapped so it can never fail the build. The zoom lightbox (open by clicking any diagram) gains **Copy** (async-clipboard image, falling back to download where unsupported) and **Download** buttons that act on the PNG for the current theme, plus a **background toggle** (checkerboard icon) that flips Copy/Download between the solid and transparent variant and previews transparency as a checkerboard on the zoom stage; inline diagrams stay button-free. The upstream `@wave-rf/astro-themed-mermaid` plugin is intentionally untouched — it's color-agnostic (CSS-var placeholders resolved at runtime), so a WYSIWYG light/dark PNG must be rasterized post-build where `global.css` + a theme apply. PNGs are gitignored build artifacts, regenerated in CI/deploy. +- **Site header override — a top-level "Docs" nav link, the search box kept expanded, and a splash-width header** (`docs/src/components/Header.astro` (new), `docs/src/config/sidebar.ts`, `docs/src/env.d.ts`, `docs/astro.config.mjs`): Starlight has no config hook for header links, so we override its `Header` component through the sanctioned `components` map. The custom header re-renders every built-in control (SiteTitle, Search, ThemeSelect, SocialIcons, LanguageSelect) through its `virtual:starlight/components/*` import — so their overrides and Pagefind search keep working untouched — and adds a `