Add JavaScript-based redirects to supplement Read the Docs redirects

Read the Docs redirects don't reliably apply when there is a
large amount of redirects defined. While this JavaScript-based
solution is not as seamless, it has no limit on how many redirects
can be defined.

Author: Calinou

_static/js/custom.js

@@ -1,4 +1,3 @@
-
 // Handle page scroll and adjust sidebar accordingly.
 
 // Each page has two scrolls: the main scroll, which is moving the content of the page;
@@ -298,6 +297,37 @@ const registerGiscus = function () {
 };
 
 $(document).ready(() => {
+  const httpResponseStatus = window.performance.getEntries()[0].responseStatus;
+  if (httpResponseStatus === 404) {
+    // Check for redirects if on a currently invalid page.
+    // This is done in JavaScript, as Read the Docs' own redirect functionality
+    // is unreliable with large amounts of redirects defined.
+    fetch("https://raw.githubusercontent.com/godotengine/godot-docs/refs/heads/master/_tools/redirects/redirects.csv")
+      .then(response => response.text())
+      .then(csvText => {
+        const lines = csvText.trim().split('\n');
+        const redirects = {};
+        for (const line of lines) {
+          if (!line.trim()) {
+            continue;
+          }
+          const [from, to] = line.split(',').map(s => s.trim());
+          if (from && to) {
+            redirects[from] = to;
+          }
+        }
+
+        if (redirects.hasOwnProperty(window.location.pathname)) {
+          const newUrl = window.location.href.replace(window.location.pathname, redirects[window.location.pathname]);
+          console.log(`Redirecting to: ${newUrl}`);
+          window.location.replace(newUrl);
+        }
+      })
+      .catch(err => {
+        console.error("Couldn't fetch redirects list:", err);
+      });
+  }
+
   // Remove the search match highlights from the page, and adjust the URL in the
   // navigation history.
   const url = new URL(location.href);

_tools/redirects/redirects.csv renamed to _static/redirects.csv

@@ -21,19 +21,26 @@ To interact with the Read the Docs API, a valid API key must be set as
 
 ## Usage
 
-Let's say we recently renamed some files in the Git branch `3.4` (compared to the `stable` branch), and now we want to create redirects for these.
-For this, we would (after setting up the API token and requirements, see Setup above):
+Let's say we recently renamed some files in the Git branch `3.4` (compared to the `stable` branch),
+and now we want to create redirects for these. For this, we would (after setting up the API token
+and requirements, see Setup above):
 
-> python convert_git_renames_to_csv.py stable 3.4
+```
+python convert_git_renames_to_csv.py stable 3.4
+```
 
 This should output a list of the redirects to create. Let's append these to the redirects file:
 
-> python convert_git_renames_to_csv.py stable 3.4 >> redirects.csv
+```
+python convert_git_renames_to_csv.py stable 3.4 >> ../../_tools/redirects.csv
+```
 
-After this, redirects for renamed files should have been appended to `redirects.csv`. You may want to double-check that!
-Now let's submit these to ReadTheDocs and create redirects there:
+After this, redirects for renamed files should have been appended to `../../_tools/redirects.csv`.
+You may want to double-check that! Now let's submit these to ReadTheDocs and create redirects there:
 
-> python create_redirects.py
+```
+python create_redirects.py
+```
 
 And that should be it!
 

_tools/redirects/README.md

@@ -50,7 +50,7 @@ def parse_command_line_args():
         "-f",
         "--file",
         metavar="file",
-        default="redirects.csv",
+        default="../../_static/redirects.csv",
         type=str,
         help="Path to a CSV file used to keep a list of redirects, containing two columns: source and destination.",
     )