From 288dfbcd214b972eae42647a21e69df933268def Mon Sep 17 00:00:00 2001
From: Adrian Henry <adrian@hungryturtlecode.com>
Date: Wed, 21 Jan 2026 03:12:53 +0000
Subject: [PATCH 1/2] feat(docs): add PostHog analytics with search tracking

- Add PostHog analytics component with EU region support
- Track search queries, results, and clicks via custom Search override
- Set up Vercel proxy rewrites to bypass ad-blockers
- Support PUBLIC_POSTHOG_KEY environment variable
- Auto-detect localhost for direct API access during development
---
 docs/astro.config.mjs                      |   4 +-
 docs/src/components/PostHog.astro          | 113 ++++
 docs/src/components/overrides/Head.astro   |  20 +
 docs/src/components/overrides/Search.astro | 650 +++++++++++++++++++++
 docs/vercel.json                           |  12 +-
 5 files changed, 797 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/components/PostHog.astro
 create mode 100644 docs/src/components/overrides/Head.astro
 create mode 100644 docs/src/components/overrides/Search.astro

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 5c9ff81..da03f45 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -13,10 +13,12 @@ export default defineConfig({
         },
       ],
       customCss: ["./src/styles/custom.css"],
-      // Component overrides for custom design
+      // Component overrides for custom design and analytics
       components: {
         Sidebar: "./src/components/overrides/Sidebar.astro",
         EditLink: "./src/components/overrides/EditLink.astro",
+        Head: "./src/components/overrides/Head.astro",
+        Search: "./src/components/overrides/Search.astro",
       },
       // Autogenerate sidebar from directory structure
       // Contributors only need to add frontmatter to control ordering
diff --git a/docs/src/components/PostHog.astro b/docs/src/components/PostHog.astro
new file mode 100644
index 0000000..9d73320
--- /dev/null
+++ b/docs/src/components/PostHog.astro
@@ -0,0 +1,113 @@
+---
+/**
+ * PostHog Analytics Component
+ *
+ * Initializes PostHog for:
+ * - Page view tracking
+ * - Autocapture (clicks, form submits)
+ * - Session replay
+ * - Custom event tracking
+ *
+ * Uses a reverse proxy through Vercel to bypass ad-blockers.
+ *
+ * Environment Variables:
+ * - PUBLIC_POSTHOG_KEY: Your PostHog project API key (required)
+ *
+ * @see https://posthog.com/docs/libraries/astro
+ */
+
+// Get PostHog key from environment variable
+// In Astro, PUBLIC_ prefixed env vars are available on the client
+const posthogKey = import.meta.env.PUBLIC_POSTHOG_KEY || "";
+---
+
+<script is:inline data-posthog-init data-posthog-key={posthogKey}>
+  // Prevent double-initialization during view transitions
+  if (!window.__posthog_initialized) {
+    window.__posthog_initialized = true;
+
+    // Get the API key from the script's data attribute
+    const scriptEl = document.querySelector("script[data-posthog-key]");
+    const posthogKey = scriptEl?.getAttribute("data-posthog-key");
+
+    if (!posthogKey) {
+      console.warn(
+        "[PostHog] No API key found. Set PUBLIC_POSTHOG_KEY environment variable.",
+      );
+    } else {
+      !(function (t, e) {
+        var o, n, p, r;
+        e.__SV ||
+          ((window.posthog = e),
+          (e._i = []),
+          (e.init = function (i, s, a) {
+            function g(t, e) {
+              var o = e.split(".");
+              (2 == o.length && ((t = t[o[0]]), (e = o[1])),
+                (t[e] = function () {
+                  t.push([e].concat(Array.prototype.slice.call(arguments, 0)));
+                }));
+            }
+            (((p = t.createElement("script")).type = "text/javascript"),
+              (p.crossOrigin = "anonymous"),
+              (p.async = !0),
+              (p.src = s.api_host + "/static/array.js"),
+              (r = t.getElementsByTagName("script")[0]).parentNode.insertBefore(
+                p,
+                r,
+              ));
+            var u = e;
+            for (
+              void 0 !== a ? (u = e[a] = []) : (a = "posthog"),
+                u.people = u.people || [],
+                u.toString = function (t) {
+                  var e = "posthog";
+                  return (
+                    "posthog" !== a && (e += "." + a),
+                    t || (e += " (stub)"),
+                    e
+                  );
+                },
+                u.people.toString = function () {
+                  return u.toString(1) + ".people (stub)";
+                },
+                o =
+                  "capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys getNextSurveyStep onSessionId".split(
+                    " ",
+                  ),
+                n = 0;
+              n < o.length;
+              n++
+            )
+              g(u, o[n]);
+            e._i.push([i, s, a]);
+          }),
+          (e.__SV = 1));
+      })(document, window.posthog || []);
+
+      // Initialize PostHog
+      // Use reverse proxy on Vercel to bypass ad-blockers
+      // Fall back to direct EU URL for local development/preview
+      const isLocalhost =
+        window.location.hostname === "localhost" ||
+        window.location.hostname === "127.0.0.1";
+      const apiHost = isLocalhost ? "https://eu.i.posthog.com" : "/ingest";
+
+      window.posthog.init(posthogKey, {
+        api_host: apiHost,
+        ui_host: "https://eu.posthog.com",
+        person_profiles: "always",
+        capture_pageview: true,
+        capture_pageleave: true,
+        autocapture: true,
+        // Enable session replay for watching user journeys
+        session_recording: {
+          maskAllInputs: false,
+          maskInputOptions: {
+            password: true,
+          },
+        },
+      });
+    }
+  }
+</script>
diff --git a/docs/src/components/overrides/Head.astro b/docs/src/components/overrides/Head.astro
new file mode 100644
index 0000000..21a8744
--- /dev/null
+++ b/docs/src/components/overrides/Head.astro
@@ -0,0 +1,20 @@
+---
+/**
+ * Custom Head Component with PostHog Analytics
+ *
+ * Extends Starlight's default Head component to inject PostHog analytics.
+ * PostHog is loaded early in the head to capture all page interactions.
+ *
+ * @see https://starlight.astro.build/guides/overriding-components/
+ */
+import PostHog from "../PostHog.astro";
+
+const { head } = Astro.locals.starlightRoute;
+---
+
+{
+  head.map(({ tag: Tag, attrs, content }) => (
+    <Tag {...attrs} set:html={content} />
+  ))
+}
+<PostHog />
diff --git a/docs/src/components/overrides/Search.astro b/docs/src/components/overrides/Search.astro
new file mode 100644
index 0000000..3334bbb
--- /dev/null
+++ b/docs/src/components/overrides/Search.astro
@@ -0,0 +1,650 @@
+---
+/**
+ * Custom Search Component with PostHog Analytics
+ *
+ * Extends Starlight's default Search component to track:
+ * - Search queries (debounced)
+ * - Search result clicks
+ * - Searches with no results
+ *
+ * @see https://starlight.astro.build/guides/overriding-components/
+ */
+import project from "virtual:starlight/project-context";
+
+const pagefindTranslations = {
+  placeholder: Astro.locals.t("search.label"),
+  ...Object.fromEntries(
+    Object.entries(Astro.locals.t.all())
+      .filter(([key]) => key.startsWith("pagefind."))
+      .map(([key, value]) => [key.replace("pagefind.", ""), value]),
+  ),
+};
+
+const dataAttributes: DOMStringMap = {
+  "data-translations": JSON.stringify(pagefindTranslations),
+};
+if (project.trailingSlash === "never")
+  dataAttributes["data-strip-trailing-slash"] = "";
+---
+
+<site-search class={Astro.props.class} {...dataAttributes}>
+  <button
+    data-open-modal
+    disabled
+    aria-label={Astro.locals.t("search.label")}
+    aria-keyshortcuts="Control+K"
+  >
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      class="search-icon"
+    >
+      <path
+        d="M21.71 20.29 18 16.61A9 9 0 1 0 16.61 18l3.68 3.68a1 1 0 0 0 1.42 0 1 1 0 0 0 0-1.39ZM11 18a7 7 0 1 1 7-7 7 7 0 0 1-7 7Z"
+      ></path>
+    </svg>
+    <span class="sl-hidden md:sl-block" aria-hidden="true"
+      >{Astro.locals.t("search.label")}</span
+    >
+    <kbd class="sl-hidden md:sl-flex" style="display: none;">
+      <kbd>{Astro.locals.t("search.ctrlKey")}</kbd><kbd>K</kbd>
+    </kbd>
+  </button>
+
+  <dialog style="padding:0" aria-label={Astro.locals.t("search.label")}>
+    <div class="dialog-frame sl-flex">
+      {
+        /* TODO: Make the layout of this button flexible to accommodate different word lengths. Currently hard-coded for English: "Cancel" */
+      }
+      <button data-close-modal class="sl-flex md:sl-hidden">
+        {Astro.locals.t("search.cancelLabel")}
+      </button>
+      {
+        import.meta.env.DEV ? (
+          <div
+            style="margin: auto; text-align: center; white-space: pre-line;"
+            dir="ltr"
+          >
+            <p>{Astro.locals.t("search.devWarning")}</p>
+          </div>
+        ) : (
+          <div class="search-container">
+            <div id="starlight__search" />
+          </div>
+        )
+      }
+    </div>
+  </dialog>
+</site-search>
+
+{
+  /**
+   * This is intentionally inlined to avoid briefly showing an invalid shortcut.
+   * Purposely using the deprecated `navigator.platform` property to detect Apple devices, as the
+   * user agent is spoofed by some browsers when opening the devtools.
+   */
+}
+<script is:inline>
+  (() => {
+    const openBtn = document.querySelector("button[data-open-modal]");
+    const shortcut = openBtn?.querySelector("kbd");
+    if (!openBtn || !(shortcut instanceof HTMLElement)) return;
+    const platformKey = shortcut.querySelector("kbd");
+    if (platformKey && /(Mac|iPhone|iPod|iPad)/i.test(navigator.platform)) {
+      platformKey.textContent = "⌘";
+      openBtn.setAttribute("aria-keyshortcuts", "Meta+K");
+    }
+    shortcut.style.display = "";
+  })();
+</script>
+
+<script>
+  import { pagefindUserConfig } from "virtual:starlight/pagefind-config";
+
+  class SiteSearch extends HTMLElement {
+    private searchDebounceTimer: ReturnType<typeof setTimeout> | null = null;
+    private lastTrackedQuery: string = "";
+
+    constructor() {
+      super();
+      const openBtn = this.querySelector<HTMLButtonElement>(
+        "button[data-open-modal]",
+      )!;
+      const closeBtn = this.querySelector<HTMLButtonElement>(
+        "button[data-close-modal]",
+      )!;
+      const dialog = this.querySelector("dialog")!;
+      const dialogFrame = this.querySelector(".dialog-frame")!;
+
+      /** Close the modal if a user clicks on a link or outside of the modal. */
+      const onClick = (event: MouseEvent) => {
+        const isLink = "href" in (event.target || {});
+        if (
+          isLink ||
+          (document.body.contains(event.target as Node) &&
+            !dialogFrame.contains(event.target as Node))
+        ) {
+          closeModal();
+        }
+      };
+
+      const openModal = (event?: MouseEvent) => {
+        dialog.showModal();
+        document.body.toggleAttribute("data-search-modal-open", true);
+        this.querySelector("input")?.focus();
+        event?.stopPropagation();
+        window.addEventListener("click", onClick);
+
+        // Track search modal opened
+        this.trackEvent("docs_search_opened", {
+          page: window.location.pathname,
+        });
+      };
+
+      const closeModal = () => dialog.close();
+
+      openBtn.addEventListener("click", openModal);
+      openBtn.disabled = false;
+      closeBtn.addEventListener("click", closeModal);
+
+      dialog.addEventListener("close", () => {
+        document.body.toggleAttribute("data-search-modal-open", false);
+        window.removeEventListener("click", onClick);
+      });
+
+      // Listen for `ctrl + k` and `cmd + k` keyboard shortcuts.
+      window.addEventListener("keydown", (e) => {
+        if ((e.metaKey === true || e.ctrlKey === true) && e.key === "k") {
+          dialog.open ? closeModal() : openModal();
+          e.preventDefault();
+        }
+      });
+
+      let translations = {};
+      try {
+        translations = JSON.parse(this.dataset.translations || "{}");
+      } catch {}
+
+      const shouldStrip = this.dataset.stripTrailingSlash !== undefined;
+      const stripTrailingSlash = (path: string) =>
+        path.replace(/(.)\/(#.*)?$/, "$1$2");
+      const formatURL = shouldStrip
+        ? stripTrailingSlash
+        : (path: string) => path;
+
+      window.addEventListener("DOMContentLoaded", () => {
+        if (import.meta.env.DEV) return;
+        const onIdle =
+          window.requestIdleCallback || ((cb) => setTimeout(cb, 1));
+        onIdle(async () => {
+          // @ts-expect-error — Missing types for @pagefind/default-ui package.
+          const { PagefindUI } = await import("@pagefind/default-ui");
+          new PagefindUI({
+            ...pagefindUserConfig,
+            element: "#starlight__search",
+            baseUrl: import.meta.env.BASE_URL,
+            bundlePath:
+              import.meta.env.BASE_URL.replace(/\/$/, "") + "/pagefind/",
+            showImages: false,
+            translations,
+            showSubResults: true,
+            processResult: (result: {
+              url: string;
+              sub_results: Array<{ url: string }>;
+            }) => {
+              result.url = formatURL(result.url);
+              result.sub_results = result.sub_results.map((sub_result) => {
+                sub_result.url = formatURL(sub_result.url);
+                return sub_result;
+              });
+            },
+          });
+
+          // Set up search tracking after PagefindUI is initialized
+          this.setupSearchTracking();
+        });
+      });
+    }
+
+    /**
+     * Track an event with PostHog if available
+     */
+    private trackEvent(eventName: string, properties: Record<string, unknown>) {
+      if (typeof window !== "undefined" && (window as any).posthog) {
+        (window as any).posthog.capture(eventName, properties);
+      }
+    }
+
+    /**
+     * Set up search query tracking with debouncing
+     */
+    private setupSearchTracking() {
+      // Wait a tick for Pagefind to render its input
+      setTimeout(() => {
+        const searchInput = document.querySelector<HTMLInputElement>(
+          ".pagefind-ui__search-input",
+        );
+
+        if (!searchInput) {
+          console.warn("[PostHog] Could not find Pagefind search input");
+          return;
+        }
+
+        // Track search queries with debouncing
+        searchInput.addEventListener("input", (e) => {
+          const query = (e.target as HTMLInputElement).value.trim();
+
+          // Clear existing timer
+          if (this.searchDebounceTimer) {
+            clearTimeout(this.searchDebounceTimer);
+          }
+
+          // Only track if query is meaningful (3+ chars) and different from last tracked
+          if (query.length >= 3 && query !== this.lastTrackedQuery) {
+            this.searchDebounceTimer = setTimeout(() => {
+              this.lastTrackedQuery = query;
+
+              // Check if there are results
+              const resultsContainer = document.querySelector(
+                ".pagefind-ui__results",
+              );
+              const hasResults =
+                resultsContainer &&
+                resultsContainer.children.length > 0 &&
+                !resultsContainer.querySelector(".pagefind-ui__message");
+
+              this.trackEvent("docs_search", {
+                query: query,
+                has_results: hasResults,
+                page: window.location.pathname,
+              });
+
+              // Track no results separately for easier analysis
+              if (!hasResults) {
+                this.trackEvent("docs_search_no_results", {
+                  query: query,
+                  page: window.location.pathname,
+                });
+              }
+            }, 1000); // 1 second debounce
+          }
+        });
+
+        // Track when a search result is clicked
+        const resultsContainer = document.querySelector("#starlight__search");
+        if (resultsContainer) {
+          resultsContainer.addEventListener("click", (e) => {
+            const link = (e.target as HTMLElement).closest("a");
+            if (link && link.href) {
+              const query = searchInput.value.trim() || this.lastTrackedQuery;
+              this.trackEvent("docs_search_result_click", {
+                query: query,
+                result_url: link.href,
+                page: window.location.pathname,
+              });
+            }
+          });
+        }
+      }, 100);
+    }
+  }
+  customElements.define("site-search", SiteSearch);
+</script>
+
+<style>
+  @layer starlight.core {
+    site-search {
+      display: contents;
+    }
+    button[data-open-modal] {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+      border: 0;
+      background-color: transparent;
+      color: var(--sl-color-gray-1);
+      cursor: pointer;
+      height: 2.5rem;
+      font-size: var(--sl-text-xl);
+    }
+
+    @media (min-width: 50rem) {
+      button[data-open-modal] {
+        border: 1px solid var(--sl-color-gray-5);
+        border-radius: 0.5rem;
+        padding-inline-start: 0.75rem;
+        padding-inline-end: 0.5rem;
+        background-color: var(--sl-color-black);
+        color: var(--sl-color-gray-2);
+        font-size: var(--sl-text-sm);
+        width: 100%;
+        max-width: 22rem;
+      }
+      button[data-open-modal]:hover {
+        border-color: var(--sl-color-gray-2);
+        color: var(--sl-color-white);
+      }
+
+      button[data-open-modal] > :last-child {
+        margin-inline-start: auto;
+      }
+    }
+
+    button > kbd {
+      border-radius: 0.25rem;
+      font-size: var(--sl-text-2xs);
+      gap: 0.25em;
+      padding-inline: 0.375rem;
+      background-color: var(--sl-color-gray-6);
+    }
+
+    kbd {
+      font-family: var(--__sl-font);
+    }
+
+    dialog {
+      margin: 0;
+      background-color: var(--sl-color-gray-6);
+      border: 1px solid var(--sl-color-gray-5);
+      width: 100%;
+      max-width: 100%;
+      height: 100%;
+      max-height: 100%;
+      box-shadow: var(--sl-shadow-lg);
+    }
+    dialog[open] {
+      display: flex;
+    }
+
+    dialog::backdrop {
+      background-color: var(--sl-color-backdrop-overlay);
+      -webkit-backdrop-filter: blur(0.25rem);
+      backdrop-filter: blur(0.25rem);
+    }
+
+    .dialog-frame {
+      position: relative;
+      overflow: auto;
+      flex-direction: column;
+      flex-grow: 1;
+      gap: 1rem;
+      padding: 1rem;
+    }
+
+    button[data-close-modal] {
+      position: absolute;
+      z-index: 1;
+      align-items: center;
+      align-self: flex-end;
+      height: calc(64px * var(--pagefind-ui-scale));
+      padding: 0.25rem;
+      border: 0;
+      background: transparent;
+      cursor: pointer;
+      color: var(--sl-color-text-accent);
+    }
+
+    #starlight__search {
+      --pagefind-ui-primary: var(--sl-color-text);
+      --pagefind-ui-text: var(--sl-color-gray-2);
+      --pagefind-ui-font: var(--__sl-font);
+      --pagefind-ui-background: var(--sl-color-black);
+      --pagefind-ui-border: var(--sl-color-gray-5);
+      --pagefind-ui-border-width: 1px;
+      --pagefind-ui-tag: var(--sl-color-gray-5);
+      --sl-search-cancel-space: 5rem;
+    }
+
+    :root[data-theme="light"] #starlight__search {
+      --pagefind-ui-tag: var(--sl-color-gray-6);
+    }
+
+    @media (min-width: 50rem) {
+      #starlight__search {
+        --sl-search-cancel-space: 0px;
+      }
+
+      dialog {
+        margin: 4rem auto auto;
+        border-radius: 0.5rem;
+        width: 90%;
+        max-width: 40rem;
+        height: max-content;
+        min-height: 15rem;
+        max-height: calc(100% - 8rem);
+      }
+
+      .dialog-frame {
+        padding: 1.5rem;
+      }
+    }
+  }
+</style>
+
+<style is:global>
+  @import url("@pagefind/default-ui/css/ui.css") layer(starlight.core);
+
+  @layer starlight.core {
+    [data-search-modal-open] {
+      overflow: hidden;
+    }
+
+    #starlight__search {
+      --sl-search-result-spacing: calc(1.25rem * var(--pagefind-ui-scale));
+      --sl-search-result-pad-inline-start: calc(
+        3.75rem * var(--pagefind-ui-scale)
+      );
+      --sl-search-result-pad-inline-end: calc(
+        1.25rem * var(--pagefind-ui-scale)
+      );
+      --sl-search-result-pad-block: calc(0.9375rem * var(--pagefind-ui-scale));
+      --sl-search-result-nested-pad-block: calc(
+        0.625rem * var(--pagefind-ui-scale)
+      );
+      --sl-search-corners: calc(0.3125rem * var(--pagefind-ui-scale));
+      --sl-search-page-icon-size: calc(1.875rem * var(--pagefind-ui-scale));
+      --sl-search-page-icon-inline-start: calc(
+        (
+            var(--sl-search-result-pad-inline-start) -
+              var(--sl-search-page-icon-size)
+          ) /
+          2
+      );
+      --sl-search-tree-diagram-size: calc(2.5rem * var(--pagefind-ui-scale));
+      --sl-search-tree-diagram-inline-start: calc(
+        (
+            var(--sl-search-result-pad-inline-start) -
+              var(--sl-search-tree-diagram-size)
+          ) /
+          2
+      );
+    }
+
+    #starlight__search .pagefind-ui__form::before {
+      --pagefind-ui-text: var(--sl-color-gray-1);
+      opacity: 1;
+    }
+
+    #starlight__search .pagefind-ui__search-input {
+      color: var(--sl-color-white);
+      font-weight: 400;
+      width: calc(100% - var(--sl-search-cancel-space));
+    }
+
+    #starlight__search input:focus {
+      --pagefind-ui-border: var(--sl-color-accent);
+    }
+
+    #starlight__search .pagefind-ui__search-clear {
+      inset-inline-end: var(--sl-search-cancel-space);
+      width: calc(60px * var(--pagefind-ui-scale));
+      padding: 0;
+      background-color: transparent;
+      overflow: hidden;
+    }
+    #starlight__search .pagefind-ui__search-clear:focus {
+      outline: 1px solid var(--sl-color-accent);
+    }
+    #starlight__search .pagefind-ui__search-clear::before {
+      content: "";
+      -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='m13.41 12 6.3-6.29a1 1 0 1 0-1.42-1.42L12 10.59l-6.29-6.3a1 1 0 0 0-1.42 1.42l6.3 6.29-6.3 6.29a1 1 0 0 0 .33 1.64 1 1 0 0 0 1.09-.22l6.29-6.3 6.29 6.3a1 1 0 0 0 1.64-.33 1 1 0 0 0-.22-1.09L13.41 12Z'/%3E%3C/svg%3E")
+        center / 50% no-repeat;
+      mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='m13.41 12 6.3-6.29a1 1 0 1 0-1.42-1.42L12 10.59l-6.29-6.3a1 1 0 0 0-1.42 1.42l6.3 6.29-6.3 6.29a1 1 0 0 0 .33 1.64 1 1 0 0 0 1.09-.22l6.29-6.3 6.29 6.3a1 1 0 0 0 1.64-.33 1 1 0 0 0-.22-1.09L13.41 12Z'/%3E%3C/svg%3E")
+        center / 50% no-repeat;
+      background-color: var(--sl-color-text-accent);
+      display: block;
+      width: 100%;
+      height: 100%;
+    }
+
+    #starlight__search .pagefind-ui__results > * + * {
+      margin-top: var(--sl-search-result-spacing);
+    }
+    #starlight__search .pagefind-ui__result {
+      border: 0;
+      padding: 0;
+    }
+
+    #starlight__search .pagefind-ui__result-nested {
+      position: relative;
+      padding: var(--sl-search-result-nested-pad-block)
+        var(--sl-search-result-pad-inline-end);
+      padding-inline-start: var(--sl-search-result-pad-inline-start);
+    }
+
+    #starlight__search
+      .pagefind-ui__result-title:not(:where(.pagefind-ui__result-nested *)),
+    #starlight__search .pagefind-ui__result-nested {
+      position: relative;
+      background-color: var(--sl-color-black);
+    }
+
+    #starlight__search
+      .pagefind-ui__result-title:not(
+        :where(.pagefind-ui__result-nested *)
+      ):hover,
+    #starlight__search
+      .pagefind-ui__result-title:not(
+        :where(.pagefind-ui__result-nested *)
+      ):focus-within,
+    #starlight__search .pagefind-ui__result-nested:hover,
+    #starlight__search .pagefind-ui__result-nested:focus-within {
+      outline: 1px solid var(--sl-color-accent-high);
+    }
+
+    #starlight__search
+      .pagefind-ui__result-title:not(
+        :where(.pagefind-ui__result-nested *)
+      ):focus-within,
+    #starlight__search .pagefind-ui__result-nested:focus-within {
+      background-color: var(--sl-color-accent-low);
+    }
+
+    #starlight__search .pagefind-ui__result-thumb,
+    #starlight__search .pagefind-ui__result-inner {
+      margin-top: 0;
+    }
+
+    #starlight__search .pagefind-ui__result-inner > :first-child {
+      border-radius: var(--sl-search-corners) var(--sl-search-corners) 0 0;
+    }
+    #starlight__search .pagefind-ui__result-inner > :last-child {
+      border-radius: 0 0 var(--sl-search-corners) var(--sl-search-corners);
+    }
+
+    #starlight__search .pagefind-ui__result-inner > .pagefind-ui__result-title {
+      padding: var(--sl-search-result-pad-block)
+        var(--sl-search-result-pad-inline-end);
+      padding-inline-start: var(--sl-search-result-pad-inline-start);
+    }
+    #starlight__search
+      .pagefind-ui__result-inner
+      > .pagefind-ui__result-title::before {
+      content: "";
+      position: absolute;
+      inset-block: 0;
+      inset-inline-start: var(--sl-search-page-icon-inline-start);
+      width: var(--sl-search-page-icon-size);
+      background: var(--sl-color-gray-3);
+      -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='currentColor' viewBox='0 0 24 24'%3E%3Cpath d='M9 10h1a1 1 0 1 0 0-2H9a1 1 0 0 0 0 2Zm0 2a1 1 0 0 0 0 2h6a1 1 0 0 0 0-2H9Zm11-3V8l-6-6a1 1 0 0 0-1 0H7a3 3 0 0 0-3 3v14a3 3 0 0 0 3 3h10a3 3 0 0 0 3-3V9Zm-6-4 3 3h-2a1 1 0 0 1-1-1V5Zm4 14a1 1 0 0 1-1 1H7a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h5v3a3 3 0 0 0 3 3h3v9Zm-3-3H9a1 1 0 0 0 0 2h6a1 1 0 0 0 0-2Z'/%3E%3C/svg%3E")
+        center no-repeat;
+      mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='currentColor' viewBox='0 0 24 24'%3E%3Cpath d='M9 10h1a1 1 0 1 0 0-2H9a1 1 0 0 0 0 2Zm0 2a1 1 0 0 0 0 2h6a1 1 0 0 0 0-2H9Zm11-3V8l-6-6a1 1 0 0 0-1 0H7a3 3 0 0 0-3 3v14a3 3 0 0 0 3 3h10a3 3 0 0 0 3-3V9Zm-6-4 3 3h-2a1 1 0 0 1-1-1V5Zm4 14a1 1 0 0 1-1 1H7a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h5v3a3 3 0 0 0 3 3h3v9Zm-3-3H9a1 1 0 0 0 0 2h6a1 1 0 0 0 0-2Z'/%3E%3C/svg%3E")
+        center no-repeat;
+    }
+
+    #starlight__search .pagefind-ui__result-inner {
+      align-items: stretch;
+      gap: 1px;
+    }
+
+    #starlight__search .pagefind-ui__result-link {
+      position: unset;
+      --pagefind-ui-text: var(--sl-color-white);
+      font-weight: 600;
+    }
+
+    #starlight__search .pagefind-ui__result-link:hover {
+      text-decoration: none;
+    }
+
+    #starlight__search
+      .pagefind-ui__result-nested
+      .pagefind-ui__result-link::before {
+      content: unset;
+    }
+
+    #starlight__search .pagefind-ui__result-nested::before {
+      content: "";
+      position: absolute;
+      inset-block: 0;
+      inset-inline-start: var(--sl-search-tree-diagram-inline-start);
+      width: var(--sl-search-tree-diagram-size);
+      background: var(--sl-color-gray-4);
+      -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' stroke='currentColor' stroke-linecap='round' viewBox='0 0 16 1000' preserveAspectRatio='xMinYMin slice'%3E%3Cpath d='M8 0v1000m6-988H8'/%3E%3C/svg%3E")
+        0% 0% / 100% no-repeat;
+      mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' stroke='currentColor' stroke-linecap='round' viewBox='0 0 16 1000' preserveAspectRatio='xMinYMin slice'%3E%3Cpath d='M8 0v1000m6-988H8'/%3E%3C/svg%3E")
+        0% 0% / 100% no-repeat;
+    }
+    #starlight__search .pagefind-ui__result-nested:last-of-type::before {
+      -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' stroke='currentColor' stroke-linecap='round' stroke-linejoin='round' viewBox='0 0 16 16'%3E%3Cpath d='M8 0v12m6 0H8'/%3E%3C/svg%3E");
+      mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' stroke='currentColor' stroke-linecap='round' stroke-linejoin='round' viewBox='0 0 16 16'%3E%3Cpath d='M8 0v12m6 0H8'/%3E%3C/svg%3E");
+    }
+
+    /* Flip page and tree icons around the vertical axis when in an RTL layout. */
+    [dir="rtl"] .pagefind-ui__result-title::before,
+    [dir="rtl"] .pagefind-ui__result-nested::before {
+      transform: matrix(-1, 0, 0, 1, 0, 0);
+    }
+
+    #starlight__search .pagefind-ui__result-link::after {
+      content: "";
+      position: absolute;
+      inset: 0;
+    }
+
+    #starlight__search .pagefind-ui__result-excerpt {
+      font-size: calc(1rem * var(--pagefind-ui-scale));
+      overflow-wrap: anywhere;
+    }
+
+    #starlight__search mark {
+      color: var(--sl-color-gray-2);
+      background-color: transparent;
+      font-weight: 600;
+    }
+
+    #starlight__search .pagefind-ui__filter-value::before {
+      border-color: var(--sl-color-text-invert);
+    }
+
+    #starlight__search .pagefind-ui__result-tags {
+      background-color: var(--sl-color-black);
+      margin-top: 0;
+      padding: var(--sl-search-result-nested-pad-block)
+        var(--sl-search-result-pad-inline-end);
+    }
+  }
+</style>
diff --git a/docs/vercel.json b/docs/vercel.json
index e37495e..eddacfc 100644
--- a/docs/vercel.json
+++ b/docs/vercel.json
@@ -2,5 +2,15 @@
   "$schema": "https://openapi.vercel.sh/vercel.json",
   "framework": "astro",
   "buildCommand": "npm run build",
-  "outputDirectory": "dist"
+  "outputDirectory": "dist",
+  "rewrites": [
+    {
+      "source": "/ingest/static/:path*",
+      "destination": "https://eu-assets.i.posthog.com/static/:path*"
+    },
+    {
+      "source": "/ingest/:path*",
+      "destination": "https://eu.i.posthog.com/:path*"
+    }
+  ]
 }

From 7e14689662af22aa923685f2b88c5fc7023d34d3 Mon Sep 17 00:00:00 2001
From: Adrian Henry <adrian@hungryturtlecode.com>
Date: Wed, 21 Jan 2026 03:27:35 +0000
Subject: [PATCH 2/2] fix(docs): add TypeScript config for Starlight virtual
 modules

- Add tsconfig.json with Starlight types
- Add env.d.ts for pagefind types
- Fix localhost detection for PostHog API host
- Remove unused @ts-expect-error directive
---
 docs/src/components/overrides/Search.astro |  1 -
 docs/src/env.d.ts                          | 23 ++++++++++++++++++++++
 docs/tsconfig.json                         | 18 +++++++++++++++++
 3 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/env.d.ts
 create mode 100644 docs/tsconfig.json

diff --git a/docs/src/components/overrides/Search.astro b/docs/src/components/overrides/Search.astro
index 3334bbb..bce5c6b 100644
--- a/docs/src/components/overrides/Search.astro
+++ b/docs/src/components/overrides/Search.astro
@@ -180,7 +180,6 @@ if (project.trailingSlash === "never")
         const onIdle =
           window.requestIdleCallback || ((cb) => setTimeout(cb, 1));
         onIdle(async () => {
-          // @ts-expect-error — Missing types for @pagefind/default-ui package.
           const { PagefindUI } = await import("@pagefind/default-ui");
           new PagefindUI({
             ...pagefindUserConfig,
diff --git a/docs/src/env.d.ts b/docs/src/env.d.ts
new file mode 100644
index 0000000..03ee87f
--- /dev/null
+++ b/docs/src/env.d.ts
@@ -0,0 +1,23 @@
+/// <reference path="../.astro/types.d.ts" />
+/// <reference types="astro/client" />
+/// <reference types="@astrojs/starlight/virtual.d.ts" />
+/// <reference types="@astrojs/starlight/virtual-internal.d.ts" />
+/// <reference types="@astrojs/starlight/locals.d.ts" />
+
+declare module "@pagefind/default-ui" {
+  export class PagefindUI {
+    constructor(options: {
+      element?: string;
+      baseUrl?: string;
+      bundlePath?: string;
+      showImages?: boolean;
+      translations?: Record<string, string>;
+      showSubResults?: boolean;
+      processResult?: (result: {
+        url: string;
+        sub_results: Array<{ url: string }>;
+      }) => void;
+      [key: string]: unknown;
+    });
+  }
+}
diff --git a/docs/tsconfig.json b/docs/tsconfig.json
new file mode 100644
index 0000000..f81698d
--- /dev/null
+++ b/docs/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "types": ["@astrojs/starlight"],
+    "baseUrl": ".",
+    "paths": {
+      "virtual:starlight/*": [
+        "./node_modules/@astrojs/starlight/virtual.d.ts",
+        "./node_modules/@astrojs/starlight/virtual-internal.d.ts"
+      ]
+    }
+  },
+  "include": [
+    "src/**/*",
+    ".astro/types.d.ts",
+    "node_modules/@astrojs/starlight/*.d.ts"
+  ]
+}