From 848610768ff2ed98bdc372ddb0ed4a57c01cea8d Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhou.song@gmail.com>
Date: Thu, 30 Jul 2026 12:39:56 -0400
Subject: [PATCH] Add a branded 404 page

Unknown URLs currently land on the unbranded Next.js default 404 (a
bare 'This page could not be found'). With the static export, a root
app/not-found.tsx is emitted as out/404.html, which GitHub Pages serves
for any unknown path.

The new page matches the site's dark styling and routes visitors to
the places a lost visitor most likely wants: docs, downloads, samples,
home, and an issue link for reporting broken links.
---
 app/not-found.tsx | 68 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 app/not-found.tsx

diff --git a/app/not-found.tsx b/app/not-found.tsx
new file mode 100644
index 0000000..cfe6ef2
--- /dev/null
+++ b/app/not-found.tsx
@@ -0,0 +1,68 @@
+import Link from "next/link";
+
+const suggestions = [
+  {
+    title: "Documentation",
+    description: "Guides, quick starts, and the MQL reference.",
+    href: "/docs",
+  },
+  {
+    title: "Download",
+    description: "Docker, APT, and RPM install commands.",
+    href: "/packages",
+  },
+  {
+    title: "Samples",
+    description: "Ready-to-run example applications.",
+    href: "/samples",
+  },
+] as const;
+
+export default function NotFound() {
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center bg-neutral-900 px-4 py-16 sm:px-6">
+      <p className="mb-3 text-xs font-semibold uppercase tracking-[0.24em] text-blue-300">
+        404 - Page not found
+      </p>
+      <h1 className="mb-4 text-center text-4xl font-extrabold tracking-tight text-white sm:text-5xl">
+        This page doesn&apos;t exist
+      </h1>
+      <p className="mb-10 max-w-xl text-center text-base leading-7 text-gray-400">
+        The page you&apos;re looking for may have moved. These are the most
+        useful places to continue from.
+      </p>
+
+      <div className="mb-10 grid w-full max-w-3xl gap-4 sm:grid-cols-3">
+        {suggestions.map((item) => (
+          <Link
+            key={item.href}
+            href={item.href}
+            className="group rounded-2xl border border-neutral-800 bg-neutral-900/80 p-5 transition hover:-translate-y-0.5 hover:border-blue-400/30 hover:bg-neutral-800/60"
+          >
+            <h2 className="mb-2 text-lg font-semibold text-white transition group-hover:text-blue-200">
+              {item.title}
+            </h2>
+            <p className="text-sm leading-6 text-gray-400">{item.description}</p>
+          </Link>
+        ))}
+      </div>
+
+      <div className="flex flex-col gap-3 sm:flex-row">
+        <Link
+          href="/"
+          className="inline-flex items-center justify-center rounded-md bg-blue-500 px-6 py-3 text-sm font-semibold text-white transition-colors hover:bg-blue-400"
+        >
+          Back to home
+        </Link>
+        <a
+          href="https://github.com/documentdb/documentdb.github.io/issues"
+          target="_blank"
+          rel="noopener noreferrer"
+          className="inline-flex items-center justify-center rounded-md border border-neutral-600 bg-neutral-800/40 px-6 py-3 text-sm font-semibold text-gray-200 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
+        >
+          Report a broken link
+        </a>
+      </div>
+    </div>
+  );
+}