Today we are announcing User-defined Redirects for Read the Docs. This has been a long requested feature that should cut down on 404’s when migrating your documentation.
Read the Docs has long had Redirects, but they are managed automatically for only certain use cases. This change allows users to control a specific set of common redirects.
The most useful and requested application of redirects was to migrate to Read the Docs from an old host. You would have your docs served at a previous URL, but that URL would break once you moved them. Read the Docs includes a language and version slug in your documentation, but not all documentation is hosted this way.
Say that you previously had your docs hosted at
and you move
docs.example.com to point at Read the Docs.
Users will have a bookmark saved to a page at
a URL that no longer exists.
You can now set a Prefix Redirect that will redirect all 404’s with a prefix to a new place. The example configuration would be:
Type: Prefix Redirect From URL: /dev/
Your user’s query would now redirect in the following manner:
docs.example.com/dev/install.html -> docs.example.com/en/latest/install.html
latest are the default language and version values for your project.
A more specific case is when you move a page around in your docs. The old page will start 404’ing, and your users will be confused. Page Redirects let you redirect a specific page.
Say you move the
example.html page into a subdirectory of examples:
You would set the following configuration:
Type: Page Redirect From URL: example.html To URL: examples/intro.html
We also support redirects for changing the type of documentation Sphinx is building.
If you switch between HTMLDir and HTML, your URL’s will change.
A page at
/en/latest/install.html will be served at
or vice versa.
The built in redirects for this will handle redirecting users appropriately.
Since we serve documentation in a highly available way, we do not run any logic when we’re serving documentation. This means that redirects will only happen in the case of a 404 File Not Found.
This is an initial attempt at redirects. We have some plans to improve this, but get in touch with us if you have ideas for improving the feature.