Customize expired preview pages

.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';
             }

.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');
 

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
 

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 %}

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 = [