User-defined Redirects¶
You can set up redirects for a project in your project dashboard’s Redirects page.
Table of contents
Quick summary¶
Go to the Admin tab of your project.
From the left navigation menu, select Redirects.
In the form box “Redirect Type” select the type of redirect you want. See below for detail.
Depending on the redirect type you select, enter
From URL
and/orTo URL
as needed.When finished, click the Add button.
Your redirects will be effective immediately.
Features¶
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, mark the Force redirect option. This option is only available on some plan levels. Please ask support if you need it for some reason.
Page redirects and Exact redirects can redirect to URLs outside Read the Docs, just include the protocol in
To URL
, e.ghttps://example.com
.
Redirect types¶
We offer a few different type of redirects based on what you want to do.
Prefix redirects¶
The most useful and requested feature of redirects was when migrating 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 https://docs.example.com/dev/
,
you move docs.example.com
to point at Read the Docs.
So users will have a bookmark saved to a page at https://docs.example.com/dev/install.html
.
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 users query would now redirect in the following manner:
docs.example.com/dev/install.html ->
docs.example.com/en/latest/install.html
Where en
and latest
are the default language and version values for your project.
Note
If you were hosting your docs without a prefix, you can create a /
Prefix Redirect,
which will prepend /$lang/$version/
to all incoming URLs.
Page redirects¶
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: examples/intro.html
.
You would set the following configuration:
Type: Page Redirect
From URL: /example.html
To URL: /examples/intro.html
Page Redirects apply to all versions of you documentation.
Because of this,
the /
at the start of the From URL
doesn’t include the /$lang/$version
prefix (e.g.
/en/latest
), but just the version-specific part of the URL.
If you want to set redirects only for some languages or some versions, you should use
Exact redirects with the fully-specified path.
Exact redirects¶
Exact Redirects are for redirecting a single URL, taking into account the full URL (including language and version).
You can also redirect a subset of URLs by including the $rest
keyword
at the end of the From URL
.
Exact redirects examples¶
Redirecting a single URL¶
Say you’re moving docs.example.com
to Read the Docs and want to redirect traffic
from an old page at https://docs.example.com/dev/install.html
to a new URL
of https://docs.example.com/en/latest/installing-your-site.html
.
The example configuration would be:
Type: Exact Redirect
From URL: /dev/install.html
To URL: /en/latest/installing-your-site.html
Your users query would now redirect in the following manner:
docs.example.com/dev/install.html ->
docs.example.com/en/latest/installing-your-site.html
Note that you should insert the desired language for “en” and version for “latest” to achieve the desired redirect.
Redirecting a whole sub-path to a different one¶
Exact Redirects could be also useful to redirect a whole sub-path to a different one by using a special $rest
keyword in the “From URL”.
Let’s say that you want to redirect your readers of your version 2.0
of your documentation under /en/2.0/
because it’s deprecated,
to the newest 3.0
version of it at /en/3.0/
.
This example would be:
Type: Exact Redirect
From URL: /en/2.0/$rest
To URL: /en/3.0/
The readers of your documentation will now be redirected as:
docs.example.com/en/2.0/dev/install.html ->
docs.example.com/en/3.0/dev/install.html
Similarly, if you maintain several branches of your documentation (e.g. 3.0
and
latest
) and decide to move pages in latest
but not the older branches, you can use
Exact Redirects to do so.
Migrating your documentation to another domain¶
You can use an exact redirect to migrate your documentation to another domain, for example:
Type: Exact Redirect
From URL: /$rest
To URL: https://newdocs.example.com/
Force Redirect: True
Then all pages will redirect to the new domain, for example
https://docs.example.com/en/latest/install.html
will redirect to
https://newdocs.example.com/en/latest/install.html
.
Sphinx redirects¶
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 /en/latest/install/
,
or vice versa.
The built in redirects for this will handle redirecting users appropriately.