How to use custom URL redirects in documentation projectsο
In this guide, you will learn the steps necessary to configure your Read the Docs project for redirecting visitors from one location to another.
User-defined redirects are issued by our servers when a reader visits an old URL, which means that the reader is automatically redirected to a new URL.
See also
- Best practices for linking to your documentation
The need for a redirect often comes from external links to your documentation. Read more about handling links in this explanation of best practices.
- Custom and built-in redirects on Read the Docs
If you want to know more about our implementation of redirects, you can look up more examples in our reference before continuing with the how-to.
Adding a redirect ruleο
Redirects are configured in the project dashboard, go to .
After clicking Add Redirect, you need to select a Redirect Type. This is where things get a bit more complicated you need to fill in specific information according to that choice.
Choosing a Redirect Typeο
There are different types of redirect rules targeting different needs. For each choice in Redirect Type, you can mark the choice in order to experiment and preview the final rule generated.
Here is a quick overview of the options available in Redirect Type:
- Prefix redirect
This option is often relevant when moving a project from a former host to Read the Docs. In this case, often URL paths hierarchies are redirected.
Read more about this option in Prefix redirects
- Page redirect
With this option, you can specify a page in your documentation to redirect elsewhere. The rule triggers no matter the version of your documentation that the user is visiting. This rule can also redirect to another website.
Read more about this option in Page redirects
- Exact redirect
With this option, you can specify a page in your documentation to redirect elsewhere. The rule is specific to the language and version of your documentation that the user is visiting. This rule can also redirect to another website.
Read more about this option in Exact redirects
- Sphinx HTMLDir => HTML
If you choose to change your Sphinx builder from DirHTML writer to the default html5writer, you can redirect all mismatches automatically.
Read more about this option in Sphinx redirects
- Sphinx HTML => HTMLDir
Similarly to the former option, if you choose to change your Sphinx builder from the default html5writer to DirHTML writer, you can redirect all mismatches automatically.
Read more about this option in Sphinx redirects
Note
By default, redirects are followed only if the requested page doesnβt exist (404 File Not Found error). If you need to apply a redirect for files that exist, you can have a Apply even if the page exists option visible. This option is only available on some plan levels. Please ask support to enable it for you.
Defining the redirect ruleο
As mentioned before, you can pick and choose a Redirect Type that fits your redirect need. When you have entered a From URL and To URL and the redirect preview looks good, you are ready to save the rule.
Saving the redirectο
The redirect is not activated before you click Save. Before clicking, you are free to experiment and preview the effects. Your redirect rules is added and effective immediately after saving it.
After adding the rule, you can add more redirects as needed. There are no immediate upper bounds to how many redirect rules a project may define.
Editing and deleting redirect rulesο
You can always revisit . in order to delete a rule or edit it.
When editing a rule, you can change its Redirect Type and its From URL or To URL.