From ea9cccb87c8fd2f1465af4d3f4c0b59c3410eea8 Mon Sep 17 00:00:00 2001
From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Fri, 6 Dec 2024 23:29:34 +0100
Subject: [PATCH 1/3] 404: be more helpful about outdated versions

People used to link to specific versions of manual pages (as reported in
https://github.com/git/git-scm.com/issues/1927).

Instead of showing a plain 404 page, try to be slightly more helpful by
telling the reader that this version no longer exists, providing a link
to the newest version.

Then, also try to figure out what the most closely-matching page is that
_is_ available, and if one is found, show that one, too.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 content/404.html | 44 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

diff --git a/content/404.html b/content/404.html
index 79772f91c5..e02a6d6a78 100644
--- a/content/404.html
+++ b/content/404.html
@@ -7,7 +7,49 @@
     <img src="{{< relurl "images/404@2x.png" >}}" alt="404" width="456" height="149" />
   </p>
   <h1>That page doesn't exist.</h1>
-  <p>
+  <p id='explanation'>
     We recently redesigned the site and older URLs may now lead to missing pages. We apologize for the inconvenience.
   </p>
+  <script>
+    /* Be more helpful for outdated manual versions */
+    const match = window.location.pathname.match(/^(.*\/docs\/([^/]*))\/([0-9.]*)$/)
+    if (match) {
+      const [, path, command, version] = match
+
+      const el = document.querySelector('#explanation')
+      el.innerHTML = `Version ${version} of <a href="${
+        path}${window.location.search}${window.location.hash
+      }">the <code>${command}</code> manual page</a> is no longer available.`
+
+      const url = window.location.href.substring(0, window.location.href.length - version.length - 1);
+      (async () => {
+        // fetch the newest version to obtain the list of versions
+        const result = await fetch(url)
+
+        const div = document.createElement('div')
+        div.innerHTML = await result.text()
+        const versions = Array.from(
+          div
+          .querySelector('#previous-versions-dropdown')
+          .querySelectorAll('.version')
+        ).map(e => e.innerHTML)
+
+        const versionCompare = (a, b) => {
+          b = String(b).split('.')
+          for (const p of String(a).split('.')) {
+            const q = b.shift()
+            if (isNaN(q)) return +1
+            if (p != q) return p - q
+          }
+          return b.length > 0 ? -1 : 0
+        }
+
+        let i = -1
+        while (i + 1 < versions.length && versionCompare(version, versions[i + 1]) < 0) i++
+        if (versions[i]) el.innerHTML += `<br />The most closesely matching page describes version <a href="${
+          path}/${versions[i]}${window.location.search}${window.location.hash
+        }">${versions[i]}</a>.`
+      })().catch(console.error)
+    }
+  </script>
 </div>

From 28e57871481c0509b2f27040e1d9891e267321e6 Mon Sep 17 00:00:00 2001
From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Fri, 6 Dec 2024 23:57:05 +0100
Subject: [PATCH 2/3] 404: avoid bogus links to non-existing pages

It is theoretically possible that a Git command no longer exists and
therefore is no longer documented, either, yet there are links out there
pointing to said documentation.

Let's try to be somewhat helpful by detecting that situation and
directing the reader to the top-level documentation page.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 content/404.html | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/content/404.html b/content/404.html
index e02a6d6a78..7efbea65c7 100644
--- a/content/404.html
+++ b/content/404.html
@@ -25,6 +25,12 @@ <h1>That page doesn't exist.</h1>
       (async () => {
         // fetch the newest version to obtain the list of versions
         const result = await fetch(url)
+        if (result.status < 200 || result.status >= 300) {
+          el.innerHTML = `The page <code>${command}</code> does not exist in <a href="${
+            path.substring(0, path.length - command.length - 1)
+          }>the documentation</a>.`
+          return
+        }
 
         const div = document.createElement('div')
         div.innerHTML = await result.text()

From 709354ddc69a956a3b17631c0cc381e8a7f8fb69 Mon Sep 17 00:00:00 2001
From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Fri, 6 Dec 2024 23:46:39 +0100
Subject: [PATCH 3/3] 404: also be more helpful about non-existing book pages

Just like was just done for non-existing documentation pages, let's be
more helpful for missing book pages, too.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 content/404.html | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/content/404.html b/content/404.html
index 7efbea65c7..6337127d53 100644
--- a/content/404.html
+++ b/content/404.html
@@ -12,7 +12,7 @@ <h1>That page doesn't exist.</h1>
   </p>
   <script>
     /* Be more helpful for outdated manual versions */
-    const match = window.location.pathname.match(/^(.*\/docs\/([^/]*))\/([0-9.]*)$/)
+    let match = window.location.pathname.match(/^(.*\/docs\/([^/]*))\/([0-9.]*)$/)
     if (match) {
       const [, path, command, version] = match
 
@@ -57,5 +57,15 @@ <h1>That page doesn't exist.</h1>
         }">${versions[i]}</a>.`
       })().catch(console.error)
     }
+
+    match = window.location.pathname.match(/^(.*\/book\/([^/]*))(\/.*)$/)
+    if (match) {
+      const [, path, rest] = match
+
+      const el = document.querySelector('#explanation')
+      el.innerHTML = `This book page was not found. <a href="${
+        path}${window.location.search}${window.location.hash
+      }">The book's front page is here</a>.`
+    }
   </script>
 </div>