starlight-theme-celestia 0.2.0

package/src/components/SiteTitleVersioned.astro

@@ -0,0 +1,62 @@
+---
+import config from "virtual:starlight/user-config";
+import VersionSelect from "./VersionSelect.astro";
+
+const { siteTitle, siteTitleHref } = Astro.locals.starlightRoute;
+
+// Resolve the logo src to a public path.
+// Starlight's default SiteTitle uses virtual:starlight/user-images which goes through
+// Astro's image pipeline, causing re-processing on each page load and logo flicker.
+// We render the logo as a plain <img> from the public directory instead.
+let logoSrc: string | undefined;
+let logoAlt = "";
+if (config.logo) {
+  logoAlt = config.logo.alt || "";
+  if ("src" in config.logo) {
+    // Single logo — resolve the public path from the src string
+    const raw = typeof config.logo.src === "string" ? config.logo.src : "";
+    logoSrc = raw.replace(/^\.\/public/, "");
+  }
+}
+---
+
+<div class="site-title-wrapper">
+  <a href={siteTitleHref} class="site-title sl-flex">
+    {logoSrc && <img alt={logoAlt} src={logoSrc} class="celestia-logo" />}
+    <span class:list={{ "sr-only": config.logo?.replacesTitle }} translate="no">
+      {siteTitle}
+    </span>
+  </a>
+  <VersionSelect />
+</div>
+
+<style>
+  .site-title-wrapper {
+    display: flex;
+    align-items: center;
+    gap: 1.25rem;
+  }
+
+  .site-title {
+    align-items: center;
+    gap: var(--sl-nav-gap);
+    font-size: var(--sl-text-h4);
+    font-weight: 600;
+    color: var(--sl-color-text-accent);
+    text-decoration: none;
+    white-space: nowrap;
+    min-width: 0;
+  }
+
+  .celestia-logo {
+    height: calc(var(--sl-nav-height) - 2 * var(--sl-nav-pad-y));
+    width: auto;
+    max-width: 100%;
+    object-fit: contain;
+    object-position: 0 50%;
+  }
+
+  span {
+    overflow: hidden;
+  }
+</style>

package/src/components/SocialIcons.astro

@@ -0,0 +1,31 @@
+---
+import { Icon } from '@astrojs/starlight/components'
+import config from 'virtual:starlight/user-config'
+
+const links = config.social || []
+
+if (!Array.isArray(links)) {
+  const message =
+    '[starlight-theme-celestia] ' +
+    'Starlight v0.33.0 changed the `social` configuration syntax. Please specify an array of link items instead of an object.\n' +
+    'See the Starlight changelog for details: https://github.com/withastro/starlight/blob/cf3cec1b/packages/starlight/CHANGELOG.md#0330\n'
+  throw new Error(message)
+}
+---
+
+{
+  links.length > 0 && (
+    <>
+      {links.map(({ label, href, icon }) => (
+        <a
+          href={href}
+          rel="me"
+          class="flex size-8 rounded-md p-2 text-(--sl-color-text) transition hover:bg-gray-400/30 focus-visible:outline-offset-1 active:scale-90"
+        >
+          <span class="sr-only">{label}</span>
+          <Icon name={icon} size="1rem" color="currentColor" />
+        </a>
+      ))}
+    </>
+  )
+}

package/src/components/ThemeProvider.astro

@@ -0,0 +1,102 @@
+{/* This is intentionally inlined to avoid FOUC. */}
+<script is:inline>
+  // Sidebar/tab override CSS that must persist across View Transitions.
+  var celestiaOverrideCSS = `
+    .sidebar-content a {
+      transition: none !important;
+      background-color: transparent !important;
+      background: none !important;
+    }
+    .sidebar-content a[aria-current="page"] {
+      color: var(--sl-color-white) !important;
+      border-left: 2px solid var(--sl-color-accent-high) !important;
+      border-radius: 0 !important;
+      padding-left: 0.5em !important;
+    }
+    [role="tablist"] [role="tab"] {
+      border: none !important;
+      box-shadow: inset 0 -1px 0 var(--sl-color-gray-5) !important;
+    }
+    [role="tablist"] [role="tab"][aria-selected="true"] {
+      box-shadow: inset 0 -2px 0 var(--sl-color-accent-high) !important;
+    }
+  `;
+
+  function ensureCelestiaOverrides() {
+    if (!document.getElementById('celestia-sidebar-overrides')) {
+      var s = document.createElement('style');
+      s.id = 'celestia-sidebar-overrides';
+      s.textContent = celestiaOverrideCSS;
+      document.head.prepend(s);
+    }
+  }
+
+  // Inject immediately
+  ensureCelestiaOverrides();
+
+  // Preserve during View Transition swaps: copy the style element into the
+  // new document before Astro replaces the current one.
+  document.addEventListener('astro:before-swap', function(e) {
+    var existing = document.getElementById('celestia-sidebar-overrides');
+    if (existing && e.newDocument) {
+      e.newDocument.head.prepend(existing.cloneNode(true));
+    }
+  });
+
+  // Fallback: re-inject after swap in case the above didn't fire
+  document.addEventListener('astro:after-swap', ensureCelestiaOverrides);
+
+  window.StarlightThemeProvider = (() => {
+    const storedTheme =
+      typeof localStorage !== 'undefined' && localStorage.getItem('starlight-theme');
+    const theme =
+      storedTheme ||
+      (window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark');
+
+    // Set theme immediately before any styles load
+    document.documentElement.dataset.theme = theme === 'light' ? 'light' : 'dark';
+    document.documentElement.style.colorScheme = theme === 'light' ? 'light' : 'dark';
+
+    // Add class to prevent transitions during initial load
+    document.documentElement.classList.add('loading');
+
+    // Disable transitions temporarily to prevent color flash on load
+    const style = document.createElement('style');
+    style.textContent = `
+      .loading *, .loading *::before, .loading *::after {
+        transition: none !important;
+        animation-duration: 0s !important;
+      }
+    `;
+    document.head.appendChild(style);
+
+    // Re-enable transitions after page is fully loaded
+    const enableTransitions = () => {
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          document.documentElement.classList.remove('loading');
+          style.remove();
+        });
+      });
+    };
+
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', enableTransitions);
+    } else {
+      enableTransitions();
+    }
+
+    return {
+      updatePickers(theme) {
+        if (theme === undefined) {
+          var stored = typeof localStorage !== 'undefined' && localStorage.getItem('starlight-theme');
+          theme = stored || 'auto';
+        }
+        document.querySelectorAll('starlight-theme-select').forEach((picker) => {
+          const select = picker.querySelector('select');
+          if (select) select.value = theme;
+        });
+      },
+    };
+  })();
+</script>

package/src/components/ThemeSelect.astro

@@ -0,0 +1,188 @@
+---
+// Custom theme select component that cycles through auto/light/dark themes
+// Note: innerHTML usage below is safe - values are hardcoded SVG constants, not user input
+---
+
+<starlight-theme-select>
+  <button
+    type="button"
+    class="theme-toggle"
+    aria-label="Toggle theme"
+    data-theme="auto"
+  >
+    <svg class="theme-icon" width="18" height="18" viewBox="0 0 24 24" fill="currentColor">
+      <path d="M4 6V16H20V6H4ZM20 18H4C2.89 18 2 17.11 2 16V6C2 4.89 2.89 4 4 4H20C21.11 4 22 4.89 22 6V16C22 17.11 21.11 18 20 18ZM23 20H1C0.45 20 0 20.45 0 21S0.45 22 1 22H23C23.55 22 24 21.55 24 21S23.55 20 23 20Z"/>
+    </svg>
+  </button>
+</starlight-theme-select>
+
+{/* Initialize button with correct theme immediately to avoid icon flash */}
+<script is:inline>
+  (function() {
+    const storedTheme = typeof localStorage !== 'undefined' && localStorage.getItem('starlight-theme');
+    const theme = storedTheme || 'auto';
+
+    // Safe: These are hardcoded SVG paths, not user input
+    const themeIcons = {
+      auto: '<path d="M4 6V16H20V6H4ZM20 18H4C2.89 18 2 17.11 2 16V6C2 4.89 2.89 4 4 4H20C21.11 4 22 4.89 22 6V16C22 17.11 21.11 18 20 18ZM23 20H1C0.45 20 0 20.45 0 21S0.45 22 1 22H23C23.55 22 24 21.55 24 21S23.55 20 23 20Z"/>',
+      light: '<path d="M12,8A4,4 0 0,0 8,12A4,4 0 0,0 12,16A4,4 0 0,0 16,12A4,4 0 0,0 12,8M12,18A6,6 0 0,1 6,12A6,6 0 0,1 12,6A6,6 0 0,1 18,12A6,6 0 0,1 12,18M20,8.69V4H15.31L12,0.69L8.69,4H4V8.69L0.69,12L4,15.31V20H8.69L12,23.31L15.31,20H20V15.31L23.31,12L20,8.69Z"/>',
+      dark: '<path d="M17.75,4.09L15.22,6.03L16.13,9.09L13.5,7.28L10.87,9.09L11.78,6.03L9.25,4.09L12.44,4L13.5,1L14.56,4L17.75,4.09M21.25,11L19.61,12.25L20.2,14.23L18.5,13.06L16.8,14.23L17.39,12.25L15.75,11L17.81,10.95L18.5,9L19.19,10.95L21.25,11M18.97,15.95C19.8,15.87 20.69,17.05 20.16,17.8C19.84,18.25 19.5,18.67 19.08,19.07C15.17,23 8.84,23 4.94,19.07C1.03,15.17 1.03,8.83 4.94,4.93C5.34,4.53 5.76,4.17 6.21,3.85C6.96,3.32 8.14,4.21 8.06,5.04C7.79,7.9 8.75,10.87 10.95,13.06C13.14,15.26 16.1,16.22 18.97,15.95M17.33,17.97C14.5,17.81 11.7,16.64 9.53,14.5C7.36,12.31 6.2,9.5 6.04,6.68C3.23,9.82 3.34,14.4 6.35,17.41C9.37,20.43 14,20.54 17.33,17.97Z"/>'
+    };
+
+    var themeLabels = { auto: 'Auto', light: 'Light', dark: 'Dark' };
+
+    var buttons = document.querySelectorAll('starlight-theme-select button');
+    buttons.forEach(function(button) {
+      button.dataset.theme = theme;
+      var icon = button.querySelector('.theme-icon');
+      if (icon) {
+        var svgContent = themeIcons[theme];
+        while (icon.firstChild) icon.removeChild(icon.firstChild);
+        var temp = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+        temp.innerHTML = svgContent;
+        while (temp.firstChild) icon.appendChild(temp.firstChild);
+      }
+      button.setAttribute('aria-label', 'Theme: ' + themeLabels[theme]);
+      button.style.visibility = 'visible';
+    });
+  })();
+</script>
+
+<style>
+  .theme-toggle {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0.4em;
+    background: transparent;
+    border: none;
+    color: var(--sl-color-text-accent);
+    cursor: pointer;
+  }
+
+  .theme-toggle:hover {
+    opacity: 0.66;
+  }
+
+  .theme-icon {
+    flex-shrink: 0;
+    width: 1.125rem;
+    height: 1.125rem;
+  }
+</style>
+
+{/* Inlined to avoid FOUC. Uses global scope from `ThemeProvider.astro` */}
+<script is:inline>
+  if (typeof StarlightThemeProvider !== 'undefined' && StarlightThemeProvider.updatePickers) {
+    StarlightThemeProvider.updatePickers();
+  }
+</script>
+
+<script>
+  type Theme = 'auto' | 'dark' | 'light';
+
+  /** Key in `localStorage` to store color theme preference at. */
+  const storageKey = 'starlight-theme';
+
+  /** Theme cycle order */
+  const themes: Theme[] = ['auto', 'light', 'dark'];
+
+  // Safe: These are hardcoded SVG paths, not user input
+  const themeIcons: Record<Theme, string> = {
+    auto: '<path d="M4 6V16H20V6H4ZM20 18H4C2.89 18 2 17.11 2 16V6C2 4.89 2.89 4 4 4H20C21.11 4 22 4.89 22 6V16C22 17.11 21.11 18 20 18ZM23 20H1C0.45 20 0 20.45 0 21S0.45 22 1 22H23C23.55 22 24 21.55 24 21S23.55 20 23 20Z"/>',
+    light: '<path d="M12,8A4,4 0 0,0 8,12A4,4 0 0,0 12,16A4,4 0 0,0 16,12A4,4 0 0,0 12,8M12,18A6,6 0 0,1 6,12A6,6 0 0,1 12,6A6,6 0 0,1 18,12A6,6 0 0,1 12,18M20,8.69V4H15.31L12,0.69L8.69,4H4V8.69L0.69,12L4,15.31V20H8.69L12,23.31L15.31,20H20V15.31L23.31,12L20,8.69Z"/>',
+    dark: '<path d="M17.75,4.09L15.22,6.03L16.13,9.09L13.5,7.28L10.87,9.09L11.78,6.03L9.25,4.09L12.44,4L13.5,1L14.56,4L17.75,4.09M21.25,11L19.61,12.25L20.2,14.23L18.5,13.06L16.8,14.23L17.39,12.25L15.75,11L17.81,10.95L18.5,9L19.19,10.95L21.25,11M18.97,15.95C19.8,15.87 20.69,17.05 20.16,17.8C19.84,18.25 19.5,18.67 19.08,19.07C15.17,23 8.84,23 4.94,19.07C1.03,15.17 1.03,8.83 4.94,4.93C5.34,4.53 5.76,4.17 6.21,3.85C6.96,3.32 8.14,4.21 8.06,5.04C7.79,7.9 8.75,10.87 10.95,13.06C13.14,15.26 16.1,16.22 18.97,15.95M17.33,17.97C14.5,17.81 11.7,16.64 9.53,14.5C7.36,12.31 6.2,9.5 6.04,6.68C3.23,9.82 3.34,14.4 6.35,17.41C9.37,20.43 14,20.54 17.33,17.97Z"/>'
+  };
+
+  /** Theme labels for display */
+  const themeLabels: Record<Theme, string> = {
+    auto: 'Auto',
+    light: 'Light',
+    dark: 'Dark'
+  };
+
+  /** Get a typesafe theme string from any JS value (unknown values are coerced to `'auto'`). */
+  const parseTheme = (theme: unknown): Theme =>
+    theme === 'auto' || theme === 'dark' || theme === 'light' ? theme : 'auto';
+
+  /** Load the user's preference from `localStorage`. */
+  const loadTheme = (): Theme =>
+    parseTheme(typeof localStorage !== 'undefined' && localStorage.getItem(storageKey));
+
+  /** Store the user's preference in `localStorage`. */
+  function storeTheme(theme: Theme): void {
+    if (typeof localStorage !== 'undefined') {
+      localStorage.setItem(storageKey, theme === 'light' || theme === 'dark' ? theme : '');
+    }
+  }
+
+  /** Get the preferred system color scheme. */
+  const getPreferredColorScheme = (): Theme =>
+    matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
+
+  /** Get the next theme in the cycle */
+  function getNextTheme(currentTheme: Theme): Theme {
+    const currentIndex = themes.indexOf(currentTheme);
+    const nextIndex = (currentIndex + 1) % themes.length;
+    return themes[nextIndex];
+  }
+
+  /** Helper to set SVG content safely using DOM methods */
+  function setSvgContent(svgElement: Element, svgMarkup: string): void {
+    while (svgElement.firstChild) svgElement.removeChild(svgElement.firstChild);
+    const temp = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    temp.innerHTML = svgMarkup;
+    while (temp.firstChild) svgElement.appendChild(temp.firstChild);
+  }
+
+  /** Update button UI, document theme, and local storage state. */
+  function onThemeChange(theme: Theme): void {
+    document.querySelectorAll('starlight-theme-select button').forEach((button) => {
+      if (button instanceof HTMLButtonElement) {
+        button.dataset.theme = theme;
+
+        const icon = button.querySelector('.theme-icon');
+        if (icon) {
+          setSvgContent(icon, themeIcons[theme]);
+        }
+
+        button.setAttribute('aria-label', `Theme: ${themeLabels[theme]}`);
+      }
+    });
+
+    const resolvedTheme = theme === 'auto' ? getPreferredColorScheme() : theme;
+    document.documentElement.dataset.theme = resolvedTheme;
+    document.documentElement.style.colorScheme = resolvedTheme;
+
+    storeTheme(theme);
+
+    if (typeof (globalThis as any).StarlightThemeProvider !== 'undefined' && (globalThis as any).StarlightThemeProvider.updatePickers) {
+      (globalThis as any).StarlightThemeProvider.updatePickers(theme);
+    }
+  }
+
+  // React to changes in system color scheme.
+  matchMedia(`(prefers-color-scheme: light)`).addEventListener('change', () => {
+    if (loadTheme() === 'auto') onThemeChange('auto');
+  });
+
+  class StarlightThemeSelect extends HTMLElement {
+    constructor() {
+      super();
+
+      const currentTheme = loadTheme();
+      onThemeChange(currentTheme);
+
+      const button = this.querySelector('button');
+      if (button) {
+        button.addEventListener('click', () => {
+          const currentTheme = parseTheme(button.dataset.theme);
+          const nextTheme = getNextTheme(currentTheme);
+          onThemeChange(nextTheme);
+        });
+      }
+    }
+  }
+
+  customElements.define('starlight-theme-select', StarlightThemeSelect);
+</script>

package/src/components/TwoColumnContent.astro

@@ -0,0 +1,44 @@
+<div class="lg:sl-flex">
+  {
+    Astro.locals.starlightRoute.toc && (
+      <aside class="right-sidebar-container print:hidden">
+        <div class="right-sidebar">
+          <slot name="right-sidebar" />
+        </div>
+      </aside>
+    )
+  }
+  <div class="main-pane"><slot /></div>
+</div>
+
+<style>
+  @layer celestia {
+    .main-pane {
+      isolation: isolate;
+      overflow-x: hidden;
+    }
+
+    @media (min-width: 72rem) {
+      .right-sidebar-container {
+        order: 2;
+        position: relative;
+        width: var(--sl-sidebar-width);
+      }
+
+      .right-sidebar {
+        position: fixed;
+        top: 0;
+        right: 0;
+        padding-top: var(--sl-nav-height);
+        height: 100vh;
+        width: var(--sl-sidebar-width);
+        overflow-y: auto;
+        scrollbar-width: none;
+      }
+
+      .main-pane {
+        flex: 1;
+      }
+    }
+  }
+</style>

package/src/components/VersionSelect.astro

@@ -0,0 +1,261 @@
+---
+/**
+ * Version dropdown selector for use with starlight-versions.
+ * This component is only rendered when starlight-versions is configured.
+ */
+import { Icon } from "@astrojs/starlight/components";
+import starlightConfig from "virtual:starlight/user-config";
+import starlightVersionsConfig from "virtual:starlight-versions-config";
+
+type Version = {
+  slug: string;
+  label?: string;
+  redirect?: "same-page" | "root";
+};
+
+function getVersionFromSlug(
+  config: typeof starlightVersionsConfig,
+  slug: string,
+): Version | undefined {
+  const segments = slug.split("/");
+  const versionOrLocaleSegment = segments[0];
+  if (!versionOrLocaleSegment) return undefined;
+  const version = config.versions.find(
+    (v: Version) => v.slug === versionOrLocaleSegment,
+  );
+  if (version) return version;
+  const locales = Object.keys(starlightConfig.locales ?? {});
+  if (!locales.includes(versionOrLocaleSegment)) return undefined;
+  const versionSegment = segments[1];
+  return config.versions.find((v: Version) => v.slug === versionSegment);
+}
+
+function stripTrailingSlash(path: string): string {
+  return path.endsWith("/") ? path.slice(0, -1) : path;
+}
+
+function getExtension(path: string): string {
+  const match = path.match(/\.[^.]+$/);
+  return match ? match[0] : "";
+}
+
+function stripExtension(path: string): string {
+  return path.replace(/\.[^.]+$/, "");
+}
+
+function getVersionURL(
+  config: typeof starlightVersionsConfig,
+  url: URL,
+  version: Version | undefined,
+): URL {
+  const versionURL = new URL(url);
+  const versionSlug = version?.slug ?? "";
+  const versionRedirect = version?.redirect ?? config.current.redirect;
+
+  const base = stripTrailingSlash(import.meta.env.BASE_URL);
+  const hasBase = versionURL.pathname.startsWith(base);
+
+  if (hasBase) {
+    versionURL.pathname = versionURL.pathname.replace(base, "");
+  }
+
+  let baseSegment: string | undefined;
+  let localeSegment: string | undefined;
+
+  const isHTML = getExtension(versionURL.pathname) === ".html";
+  const [, firstSegment, secondSegment] = versionURL.pathname.split("/");
+
+  if (starlightConfig.isMultilingual || starlightConfig.locales) {
+    const versionOrLocale = firstSegment?.replace(".html", "");
+    const isRootLocale =
+      versionOrLocale &&
+      !Object.keys(starlightConfig.locales ?? {}).includes(versionOrLocale);
+    baseSegment = isRootLocale ? firstSegment : secondSegment;
+
+    if (!isRootLocale) {
+      localeSegment = versionOrLocale;
+      versionURL.pathname = versionURL.pathname.replace(
+        `/${firstSegment}`,
+        "",
+      );
+    }
+  } else {
+    baseSegment = firstSegment;
+  }
+
+  const isRootHTML = baseSegment && getExtension(baseSegment) === ".html";
+  const baseSlug =
+    baseSegment && isRootHTML ? stripExtension(baseSegment) : baseSegment;
+
+  if (baseSlug && baseSlug in config.versionsBySlug) {
+    if (versionSlug) {
+      versionURL.pathname =
+        versionRedirect === "same-page"
+          ? versionURL.pathname.replace(baseSlug, versionSlug)
+          : `${versionSlug}${isHTML ? ".html" : "/"}`;
+    } else if (isRootHTML) {
+      versionURL.pathname = "/index.html";
+    } else {
+      versionURL.pathname =
+        versionRedirect === "same-page"
+          ? versionURL.pathname.replace(`/${baseSlug}`, "")
+          : isHTML
+            ? "/index.html"
+            : "/";
+    }
+  } else if (versionSlug) {
+    versionURL.pathname =
+      baseSegment === "index.html"
+        ? `/${versionSlug}.html`
+        : versionRedirect === "same-page"
+          ? `/${versionSlug}${versionURL.pathname}`
+          : isHTML
+            ? `${versionSlug}.html`
+            : `/${versionSlug}/`;
+  } else if (versionRedirect === "root" && !isRootHTML) {
+    versionURL.pathname = isHTML ? "/index.html" : versionSlug;
+  }
+
+  if (localeSegment) {
+    versionURL.pathname = isHTML
+      ? versionURL.pathname === "/index.html"
+        ? `/${localeSegment}.html`
+        : `/${localeSegment}${versionURL.pathname.replace(/\/$/, ".html")}`
+      : `/${localeSegment}${versionURL.pathname}`;
+  }
+
+  if (hasBase) {
+    versionURL.pathname = base + versionURL.pathname;
+  }
+
+  return versionURL;
+}
+
+const hasVersions = starlightVersionsConfig.versions.length > 0;
+const { id } = Astro.locals.starlightRoute;
+const pageVersion = hasVersions
+  ? getVersionFromSlug(starlightVersionsConfig, id)
+  : undefined;
+---
+
+{hasVersions && <starlight-version-select>
+  <label>
+    <span class="sr-only">Select version</span>
+    <Icon name="open-book" class="icon label-icon" />
+    <select
+      value={pageVersion?.label ?? starlightVersionsConfig.versions[0]?.label}
+      autocomplete="off"
+    >
+      {
+        starlightVersionsConfig.versions.map((version: Version) => (
+          <option
+            selected={
+              version.slug === pageVersion?.slug ||
+              (pageVersion === undefined &&
+                version === starlightVersionsConfig.versions[0])
+            }
+            value={
+              getVersionURL(starlightVersionsConfig, Astro.url, version)
+                .pathname
+            }
+          >
+            {version.label ?? version.slug}
+          </option>
+        ))
+      }
+    </select>
+    <Icon name="down-caret" class="icon caret-icon" />
+  </label>
+</starlight-version-select>}
+
+<style>
+  label {
+    --sl-versions-label-icon-size: 0.75rem;
+    --sl-versions-caret-icon-size: 1rem;
+
+    align-items: center;
+    color: var(--sl-color-gray-1);
+    display: flex;
+    gap: 0.125rem;
+    position: relative;
+    font-size: 0.8rem;
+  }
+
+  label:hover {
+    color: var(--sl-color-gray-2);
+  }
+
+  .icon {
+    pointer-events: none;
+    position: absolute;
+    top: 50%;
+    transform: translateY(-50%);
+  }
+
+  .label-icon {
+    font-size: var(--sl-versions-label-icon-size);
+    inset-inline-start: 0;
+  }
+
+  .caret-icon {
+    font-size: var(--sl-versions-caret-icon-size);
+    inset-inline-end: 0;
+  }
+
+  select {
+    appearance: none;
+    background-color: transparent;
+    border: 0;
+    color: inherit;
+    cursor: pointer;
+    font-size: 0.8rem;
+    padding-block: 0.375rem;
+    padding-inline: calc(var(--sl-versions-label-icon-size) + 0.25rem)
+      calc(var(--sl-versions-caret-icon-size) + 0.125rem);
+    text-overflow: ellipsis;
+    width: 4.5rem;
+  }
+
+  option {
+    background-color: var(--sl-color-bg-nav);
+    color: var(--sl-color-gray-1);
+  }
+
+  @media (min-width: 50rem) {
+    select {
+      font-size: 0.8rem;
+    }
+  }
+</style>
+
+<script>
+  if (!customElements.get("starlight-version-select")) {
+    customElements.define(
+      "starlight-version-select",
+      class StarlightVersionSelect extends HTMLElement {
+        constructor() {
+          super();
+          const select = this.querySelector("select");
+          if (!select) return;
+
+          select.addEventListener("change", (event) => {
+            if (event.currentTarget instanceof HTMLSelectElement) {
+              globalThis.location.pathname = event.currentTarget.value;
+            }
+          });
+
+          window.addEventListener("pageshow", (event) => {
+            if (!event.persisted) return;
+            const markupSelectedIndex =
+              select.querySelector<HTMLOptionElement>(
+                "option[selected]",
+              )?.index;
+            if (markupSelectedIndex !== select.selectedIndex) {
+              select.selectedIndex = markupSelectedIndex ?? 0;
+            }
+          });
+        }
+      },
+    );
+  }
+</script>