feat(docs): override Starlight header with a top-level site nav

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",

docs/src/components/Header.astro

@@ -0,0 +1,237 @@
+---
+// 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 <header class="header"> (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.
+//
+// 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 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";
+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 — 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";
+---
+
+<div class="header">
+  <div class="wh-lead">
+    <div class="title-wrapper sl-flex">
+      <SiteTitle />
+    </div>
+    <nav
+      class="wh-header-nav sl-hidden md:sl-flex print:hidden"
+      aria-label="Primary"
+    >
+      {
+        headerNav.map(({ label, href }) => (
+          <a
+            href={href}
+            class="wh-header-nav__link"
+            aria-current={
+              currentPath === href || currentPath.startsWith(`${href}/`)
+                ? "page"
+                : undefined
+            }
+          >
+            {label}
+          </a>
+        ))
+      }
+    </nav>
+  </div>
+
+  <div class="wh-right">
+    {
+      shouldRenderSearch && (
+        <div class="wh-search sl-flex print:hidden">
+          <Search />
+        </div>
+      )
+    }
+    <div class="wh-controls sl-hidden md:sl-flex print:hidden">
+      <div class="sl-flex social-icons">
+        <SocialIcons />
+      </div>
+      <ThemeSelect />
+      <LanguageSelect />
+      <a class="wh-cta" href={ctaHref}>Get Started</a>
+    </div>
+  </div>
+</div>
+
+<style>
+  /* Our own layout, held in a centered column that matches the page content
+     (~68rem, like the splash hero) instead of Starlight's edge-to-edge row.
+     The outer PageFrame bar still spans full width; only this inner content is
+     capped + centered. Unlayered so it authoritatively styles this component's
+     inner .header row (Starlight's own rules are @layer'd and would otherwise
+     win). */
+  .header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 1rem;
+    height: 100%;
+    /* Doc pages: full-bleed to the bar edges, like Supabase/ClickHouse docs. */
+  }
+  /* Splash homepage (the only page with a hero): hold the header in a centered
+     content-width column instead. Keyed off the hero's presence in the body —
+     the same signal global.css uses — rather than an SSR class/attribute on the
+     header, because vtbot's <ReplacementSwap/> PRESERVES the header element
+     across view-transitions while swapping the body content: a baked-in
+     attribute would go stale, but this `:has()` selector re-evaluates live. */
+  :global(body:has(.wh-hero)) .header {
+    max-width: 68rem;
+    margin-inline: auto;
+  }
+
+  .wh-lead {
+    display: flex;
+    align-items: center;
+    gap: 1.75rem;
+    min-width: 0;
+  }
+  .title-wrapper {
+    /* Avoid clipping the focus ring around the title link. */
+    padding: 0.25rem;
+    margin: -0.25rem;
+    min-width: 0;
+  }
+
+  .wh-right {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+  }
+  /* No `display` here on purpose — let the `sl-hidden md:sl-flex` utilities
+     govern visibility so the controls collapse under 50rem (an unlayered
+     `display: flex` would override Starlight's layered `sl-hidden`). This only
+     styles the flex row they become at >=50rem. */
+  .wh-controls {
+    align-items: center;
+    gap: 1rem;
+  }
+  .social-icons {
+    align-items: center;
+    gap: 1rem;
+  }
+  /* Hairline divider before the theme/lang controls, matching the default. */
+  .social-icons::after {
+    content: "";
+    height: 1.5rem;
+    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. */
+  .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%;
+  }
+  /* Splash: collapse to a compact icon button (its "Search" label + ⌘K hint
+     are already md-only) that opens the same modal, 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;
+  }
+  :global(body:has(.wh-hero)) .wh-search :global(button[data-open-modal]) {
+    width: auto;
+    min-width: 0;
+    padding: 0.5rem;
+    gap: 0;
+  }
+
+  /* Primary nav links — quiet by default, brand accent when current. */
+  .wh-header-nav {
+    align-items: center;
+    gap: 1.5rem;
+  }
+  .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;
+    font-weight: 500;
+    line-height: 1;
+    text-decoration: none;
+    white-space: nowrap;
+    transition: color 0.15s ease;
+  }
+  .wh-header-nav__link:hover {
+    color: var(--wh-ink);
+  }
+  .wh-header-nav__link[aria-current="page"] {
+    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;
+    }
+  }
+</style>

docs/src/config/sidebar.ts

@@ -83,3 +83,13 @@ export const sidebar: StarlightUserConfig["sidebar"] = [
     ],
   },
 ];
+
+// 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: "Docs", href: "/getting-started" },
+];

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;
+}