From d0b3d8069c5c21251ca258c0300608b1ae0b6c3c 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..954aacda1e 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 dd062e2e9c81b85a2f3da7d87dc7e79715c35b6a 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 954aacda1e..6fd480fc0d 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 fa004ea85b171d6159b9338f300801ac118c67dc 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 6fd480fc0d..f1e80254a1 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>