From 105124f6031f9854d244ac845edc0d104eb2bd87 Mon Sep 17 00:00:00 2001
From: Johnny Greco <jogreco@nvidia.com>
Date: Mon, 20 Jul 2026 21:50:53 +0000
Subject: [PATCH] Customize expired preview pages

Signed-off-by: Johnny Greco <jogreco@nvidia.com>
---
 .github/workflows/docs-preview-deploy.yml |  3 ++-
 .github/workflows/docs-preview.yml        |  3 ++-
 docs/development/index.md                 |  4 +++-
 overrides/404.html                        | 28 +++++++++++++++++++++++
 zensical.toml                             |  1 +
 5 files changed, 36 insertions(+), 3 deletions(-)
 create mode 100644 overrides/404.html

diff --git a/.github/workflows/docs-preview-deploy.yml b/.github/workflows/docs-preview-deploy.yml
index efabe2d2..39331502 100644
--- a/.github/workflows/docs-preview-deploy.yml
+++ b/.github/workflows/docs-preview-deploy.yml
@@ -102,7 +102,8 @@ jobs:
                 'zensical.toml',
               ]);
               const docsChanged = files.some(
-                ({ filename }) => filename.startsWith('docs/') || exactInputs.has(filename),
+                ({ filename }) => filename.startsWith('docs/') ||
+                  filename.startsWith('overrides/') || exactInputs.has(filename),
               );
               operation = docsChanged ? 'deploy' : 'remove';
             }
diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml
index 15fc3df0..a6915ff9 100644
--- a/.github/workflows/docs-preview.yml
+++ b/.github/workflows/docs-preview.yml
@@ -50,7 +50,8 @@ jobs:
               'zensical.toml',
             ]);
             const docsChanged = files.some(
-              ({ filename }) => filename.startsWith('docs/') || exactInputs.has(filename),
+              ({ filename }) => filename.startsWith('docs/') ||
+                filename.startsWith('overrides/') || exactInputs.has(filename),
             );
             core.setOutput('operation', docsChanged ? 'deploy' : 'remove');
 
diff --git a/docs/development/index.md b/docs/development/index.md
index d27d83e6..db4c4f51 100644
--- a/docs/development/index.md
+++ b/docs/development/index.md
@@ -56,7 +56,9 @@ local Downloads directory.
 
 Verify branded surfaces in both the `default` and `slate` palette schemes. Prefer
 CSS variables in `docs/stylesheets/dev-notes.css` over one-off hard-coded colors.
-Keep asset paths relative to `docs_dir`.
+Keep asset paths relative to `docs_dir`. Theme templates live in `overrides/`;
+keep the custom `404.html` useful for ordinary missing pages as well as expired
+pull request previews.
 
 ## Validate and preview
 
diff --git a/overrides/404.html b/overrides/404.html
new file mode 100644
index 00000000..a2a87005
--- /dev/null
+++ b/overrides/404.html
@@ -0,0 +1,28 @@
+{% extends "main.html" %}
+
+{% block htmltitle %}
+  <title>Page not found - {{ config.site_name }}</title>
+{% endblock %}
+
+{% block content %}
+  <h1>Page not found</h1>
+  <p id="not-found-message">The requested documentation page does not exist.</p>
+  <p>
+    <a id="not-found-home" href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}">
+      Return to OpenShell Research
+    </a>
+  </p>
+  <script>
+    (() => {
+      const previewPath = window.location.pathname.match(
+        /^(.*\/)pr-preview\/pr-[1-9][0-9]*(?:\/|$)/,
+      );
+      if (previewPath) {
+        document.title = `Preview unavailable - {{ config.site_name }}`;
+        document.getElementById("not-found-message").textContent =
+          "This pull request preview has expired or was removed.";
+        document.getElementById("not-found-home").href = previewPath[1];
+      }
+    })();
+  </script>
+{% endblock %}
diff --git a/zensical.toml b/zensical.toml
index 5a16db11..c714228b 100644
--- a/zensical.toml
+++ b/zensical.toml
@@ -30,6 +30,7 @@ homepage = "."
 generator = false
 
 [project.theme]
+custom_dir = "overrides"
 favicon = "assets/brand/favicon.svg"
 logo = "assets/brand/openshell-mark.svg"
 features = [