Skip to content

Add JavaScript-based redirects to supplement Read the Docs redirects #11304

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 4, 2025
Merged

Add JavaScript-based redirects to supplement Read the Docs redirects #11304

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 31 additions & 1 deletion _static/js/custom.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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;
Expand Down Expand Up @@ -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 we exceed Read the Docs' limit for the amount of redirects configurable.
// When testing this feature on a local web server, replace the URL below with just `/_static/redirects.csv`.
fetch("/en/latest/_static/redirects.csv")
.then(response => response.text())
.then(csvText => {
const lines = csvText.trim().split('\n');
for (const line of lines) {
if (!line.trim()) {
continue;
}
const [from, to] = line.split(',').map(s => s.trim());
if (from && to) {
if (window.location.pathname.endsWith(from)) {
if (to.startsWith('https://')) {
window.location.replace(to);
} else {
const newUrl = window.location.href.replace(window.location.pathname, to);
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);
Expand Down
28 changes: 14 additions & 14 deletions _tools/redirects/redirects.csv → _static/redirects.csv
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -431,20 +431,20 @@ source,destination
/contributing/workflow/testing_pull_requests.html,https://contributing.godotengine.org/en/latest/organization/pull_requests/testing.html
/contributing/development/core_and_modules/2d_coordinate_systems.html,/engine_details/architecture/2d_coordinate_systems.html
/contributing/development/core_and_modules/common_engine_methods_and_macros.html,/engine_details/architecture/common_engine_methods_and_macros.html
/contributing/development/core_and_modules/core_types.html,//architecture/core_types.html
/contributing/development/core_and_modules/custom_audiostreams.html,//architecture/custom_audiostreams.html
/contributing/development/core_and_modules/custom_godot_servers.html,//architecture/custom_godot_servers.html
/contributing/development/core_and_modules/custom_modules_in_cpp.html,//architecture/custom_modules_in_cpp.html
/contributing/development/core_and_modules/custom_platform_ports.html,//architecture/custom_platform_ports.html
/contributing/development/core_and_modules/custom_resource_format_loaders.html,//architecture/custom_resource_format_loaders.html
/contributing/development/core_and_modules/godot_architecture_diagram.html,//architecture/godot_architecture_diagram.html
/contributing/development/core_and_modules/index.html,//architecture/index.html
/contributing/development/core_and_modules/inheritance_class_tree.html,//architecture/inheritance_class_tree.html
/contributing/development/core_and_modules/internal_rendering_architecture.html,//architecture/internal_rendering_architecture.html
/contributing/development/core_and_modules/object_class.html,//architecture/object_class.html
/contributing/development/core_and_modules/scripting_development.html,//architecture/scripting_development.html
/contributing/development/core_and_modules/unit_testing.html,//architecture/unit_testing.html
/contributing/development/core_and_modules/variant_class.html,//architecture/variant_class.html
/contributing/development/core_and_modules/core_types.html,/engine_details/architecture/core_types.html
/contributing/development/core_and_modules/custom_audiostreams.html,/engine_details/architecture/custom_audiostreams.html
/contributing/development/core_and_modules/custom_godot_servers.html,/engine_details/architecture/custom_godot_servers.html
/contributing/development/core_and_modules/custom_modules_in_cpp.html,/engine_details/architecture/custom_modules_in_cpp.html
/contributing/development/core_and_modules/custom_platform_ports.html,/engine_details/architecture/custom_platform_ports.html
/contributing/development/core_and_modules/custom_resource_format_loaders.html,/engine_details/architecture/custom_resource_format_loaders.html
/contributing/development/core_and_modules/godot_architecture_diagram.html,/engine_details/architecture/godot_architecture_diagram.html
/contributing/development/core_and_modules/index.html,/engine_details/architecture/index.html
/contributing/development/core_and_modules/inheritance_class_tree.html,/engine_details/architecture/inheritance_class_tree.html
/contributing/development/core_and_modules/internal_rendering_architecture.html,/engine_details/architecture/internal_rendering_architecture.html
/contributing/development/core_and_modules/object_class.html,/engine_details/architecture/object_class.html
/contributing/development/core_and_modules/scripting_development.html,/engine_details/architecture/scripting_development.html
/contributing/development/core_and_modules/unit_testing.html,/engine_details/architecture/unit_testing.html
/contributing/development/core_and_modules/variant_class.html,/engine_details/architecture/variant_class.html
/contributing/documentation/class_reference_primer.html,engine_details/class_reference/index.html
/contributing/development/compiling/compiling_for_android.html,/engine_details/development/compiling/compiling_for_android.html,
/contributing/development/compiling/compiling_for_ios.html,/engine_details/development/compiling/compiling_for_ios.html
Expand Down
21 changes: 14 additions & 7 deletions _tools/redirects/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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!

Expand Down
2 changes: 1 addition & 1 deletion _tools/redirects/create_redirects.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.",
)
Expand Down
Loading