From 4c22aafb3568565031a44cc1d17aa70b9ad4cc52 Mon Sep 17 00:00:00 2001
From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Date: Mon, 8 Jun 2026 12:11:35 -0600
Subject: [PATCH 1/2] feat: add custom 404 page with Rudderstack docs_404
 tracking
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Overrides Starlight's built-in 404 to fire a `docs_404` track event
via Rudderstack with the originally-requested broken URL and referrer.

Without this, every 404 hit logs https://docs.warp.dev/404/ as the
page URL in analytics — hiding which paths are actually broken. The
new event captures `broken_url` (window.location.href) and
`referrer` (document.referrer) so we can identify the top missing
redirects and fix them systematically.

The script uses the RS queue pattern (is:inline + window.rudderanalytics)
so it fires reliably before the async SDK finishes loading.

Part of the broken-redirects fix plan.

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/pages/404.astro | 71 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 src/pages/404.astro

diff --git a/src/pages/404.astro b/src/pages/404.astro
new file mode 100644
index 00000000..039a506c
--- /dev/null
+++ b/src/pages/404.astro
@@ -0,0 +1,71 @@
+---
+/**
+ * Custom 404 page.
+ *
+ * Overrides Starlight's built-in 404 so we can fire a Rudderstack `docs_404`
+ * track event with the originally-requested URL. Without this, every 404
+ * visit logs `https://docs.warp.dev/404/` — hiding which paths are actually
+ * broken.
+ *
+ * Uses StarlightPage so the full site chrome (nav, head, Rudderstack snippet,
+ * Vercel Analytics) is inherited automatically.
+ */
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+---
+
+<StarlightPage
+	frontmatter={{
+		title: 'Page not found',
+		description: 'The page you are looking for does not exist or has moved.',
+		template: 'splash',
+	}}
+>
+	<div class="not-found">
+		<p>
+			The page you are looking for does not exist or has been moved. Use the search or navigation
+			to find what you need.
+		</p>
+		<p>
+			<a href="/">Go to the docs home</a>
+		</p>
+	</div>
+</StarlightPage>
+
+<!--
+	Fire a docs_404 track event with the broken URL.
+
+	`window.location.href` is the actual URL the visitor tried to reach — not
+	`/404/`. This fires through the RudderStack queue so it works even before
+	the async SDK has fully loaded. Once the SDK initialises, all queued calls
+	are flushed in order.
+
+	We read the values synchronously in is:inline so they are captured before
+	any navigation or history manipulation could change them.
+-->
+<script is:inline>
+	(function () {
+		var brokenUrl = window.location.href;
+		var referrer = document.referrer || '';
+
+		// rudderanalytics is guaranteed to be a queue array at this point
+		// (the stub in RudderStackAnalytics.astro sets it up before this runs).
+		// Calling .track() on the queue simply pushes the call; once the real
+		// SDK loads it replays the queue automatically.
+		if (window.rudderanalytics) {
+			window.rudderanalytics.track('docs_404', {
+				broken_url: brokenUrl,
+				referrer: referrer,
+			});
+		}
+	})();
+</script>
+
+<style>
+	.not-found {
+		max-width: 40rem;
+	}
+
+	.not-found p {
+		margin-block: 1rem;
+	}
+</style>

From d91f846464b078f5c40a76d5162eba0a240e3a62 Mon Sep 17 00:00:00 2001
From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Date: Mon, 8 Jun 2026 12:28:38 -0600
Subject: [PATCH 2/2] Update src/pages/404.astro

Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>
---
 src/pages/404.astro | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/pages/404.astro b/src/pages/404.astro
index 039a506c..a55afa9a 100644
--- a/src/pages/404.astro
+++ b/src/pages/404.astro
@@ -44,8 +44,8 @@ import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 -->
 <script is:inline>
 	(function () {
-		var brokenUrl = window.location.href;
-		var referrer = document.referrer || '';
+		var brokenUrl = window.location.origin + window.location.pathname;
+		var referrer = document.referrer ? new URL(document.referrer).origin : '';
 
 		// rudderanalytics is guaranteed to be a queue array at this point
 		// (the stub in RudderStackAnalytics.astro sets it up before this runs).