Show the site-wide banner at the top of the docs

src/components/starlight-overrides/Header.astro

@@ -1,8 +1,36 @@
 ---
 import Default from "@astrojs/starlight/components/Header.astro";
+import Banner from "../ui/Banner.astro";
 import CookiePopup from "../ui/CookiePopup.astro";
 ---
 
 <CookiePopup />
-{/* Render the default sidebar. */}
-<Default><slot /></Default>
+{
+  /*
+    Starlight's header is position: fixed and everything else in the layout is
+    offset by --sl-nav-height. We render the banner inside the header, at its
+    top, and reserve room for it by adding --hh-docs-banner-height to
+    --sl-nav-height in custom-starlight-theme.css.
+  */
+}
+<div class="docs-banner">
+  <Banner />
+</div>
+<div class="header-content">
+  <Default><slot /></Default>
+</div>
+
+<style>
+  .docs-banner {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: var(--hh-docs-banner-height);
+  }
+
+  .header-content {
+    height: 100%;
+    padding-top: var(--hh-docs-banner-height);
+  }
+</style>

src/components/landing/Banner.astro → src/components/ui/Banner.astro

@@ -1,7 +1,7 @@
 ---
-import { landing } from "../../config";
+import { banner } from "../../config";
 
-const { text, href } = landing.banner;
+const { text, href } = banner;
 ---
 
 <a href={href} target="_blank" rel="noreferrer" class="banner-link">
@@ -29,15 +29,16 @@ const { text, href } = landing.banner;
 <style lang="sass">
   @use '../../styles/mixins' as *
 
+  // Positioning (sticky on the landing, inside the fixed header in the docs)
+  // is up to the parent.
   .banner-link
     text-decoration: none
-    position: sticky
-    top: 0
-    z-index: 19
     display: block
 
   .banner
-    font-family: var(--font-code)
+    // The docs don't load the landing fonts, so fall back to Starlight's
+    // monospace stack there.
+    font-family: var(--font-code, var(--sl-font-system-mono, monospace))
     user-select: none
     z-index: 100
     width: 100%
@@ -49,7 +50,7 @@ const { text, href } = landing.banner;
     text-align: center
     background-color: var(--hh-gray900)
     color: var(--hh-neutral0)
-    font-weight: 600
+    font-weight: 500
     line-height: 1.2
     letter-spacing: 0.02em
     cursor: pointer

src/config.ts

@@ -1,4 +1,5 @@
 import type {
+  BannerConfig,
   CookiePopupConfig,
   GlobalConfig,
   LandingConfig,
@@ -19,17 +20,19 @@ export const globalConfig: GlobalConfig = {
     - Providing an Accept header with text/markdown`,
 };
 
+// Shown at the top of both the landing page and the docs.
+export const banner: BannerConfig = {
+  text: "Compile Solidity up to 5x faster: slang-solx",
+  href: "https://blog.nomic.foundation/announcing-slang-solx-a-solidity-compiler-thats-up-to-5x-faster/",
+};
+
 export const landing: LandingConfig = {
   head: {
     title: "Hardhat 3",
     description:
       "Hardhat is an Ethereum development environment. Compile your contracts and run them on a development network. Get Solidity stack traces, console.log and more.",
     canonicalUrl: globalConfig.url,
   },
-  banner: {
-    text: "Compile Solidity up to 5x faster: slang-solx",
-    href: "https://blog.nomic.foundation/announcing-slang-solx-a-solidity-compiler-thats-up-to-5x-faster/",
-  },
   header: {
     logo: {
       url: "/",

src/configTypes.ts

@@ -5,16 +5,17 @@ export interface GlobalConfig {
   headCommentForAgents: string;
 }
 
+export interface BannerConfig {
+  text: string;
+  href: string;
+}
+
 export interface LandingConfig {
   head: {
     title: string;
     description: string;
     canonicalUrl: string;
   };
-  banner: {
-    text: string;
-    href: string;
-  };
   header: {
     logo: {
       url: string;

src/pages/index.astro

@@ -2,7 +2,7 @@
 import "../styles/landing.css";
 
 import { globalConfig, landing } from "../config";
-import Banner from "../components/landing/Banner.astro";
+import Banner from "../components/ui/Banner.astro";
 import EmailForm from "../components/landing/EmailForm.astro";
 import Footer from "../components/landing/Footer.astro";
 import HardhatNews from "../components/landing/HardhatNews.astro";
@@ -85,7 +85,9 @@ ${globalConfig.headCommentForAgents}
     />
   </head>
   <body>
-    <Banner />
+    <div class="banner-sticky">
+      <Banner />
+    </div>
     <LandingHeader />
 
     <main class="main">
@@ -99,3 +101,11 @@ ${globalConfig.headCommentForAgents}
     <CookiePopup />
   </body>
 </html>
+
+<style>
+  .banner-sticky {
+    position: sticky;
+    top: 0;
+    z-index: 19;
+  }
+</style>

src/styles/custom-starlight-theme.css

@@ -1,5 +1,37 @@
 @import url(./colors.css);
 
+/*
+  Site-wide banner at the top of the docs. It renders inside Starlight's fixed
+  header (see starlight-overrides/Header.astro), so we grow --sl-nav-height by
+  its height: the sidebar, main frame, mobile TOC, right sidebar and scroll
+  padding all derive from that variable and clear the banner automatically.
+  Only the two pieces that center themselves within the header height need to
+  subtract it again.
+*/
+:root {
+  --hh-docs-banner-height: 40px;
+  --sl-nav-height: calc(3.5rem + var(--hh-docs-banner-height));
+}
+
+@media (min-width: 50em) {
+  :root {
+    --sl-nav-height: calc(4rem + var(--hh-docs-banner-height));
+  }
+}
+
+.site-title img {
+  height: calc(
+    var(--sl-nav-height) - var(--hh-docs-banner-height) - 2 * var(--sl-nav-pad-y)
+  );
+}
+
+starlight-menu-button button {
+  top: calc(
+    var(--hh-docs-banner-height) +
+      (var(--sl-nav-height) - var(--hh-docs-banner-height) - var(--sl-menu-button-size)) / 2
+  );
+}
+
 :root[data-theme='dark'] {
   --sl-color-accent-low:  var(--hh-yellow1150);  /* subtle accent bg (chips, callouts) */
   --sl-color-accent:      var(--hh-accent700);  /* main link color on dark (very bright) */