Redirects
Over time, a documentation project may want to rename and move contents around. Redirects allow changes in a documentation project to happen without bad user experiences.
If you do not manage URL structures, users will eventually encounter 404 File Not Found errors. While this may be acceptable in some cases, the bad user experience of a 404 page is usually best to avoid.
- Built-in redirects ⬇️
Allows for simple and long-term sharing of external references to your documentation.
- User-defined redirects ⬇️
Makes it easier to move contents around
See also
- How to use custom URL redirects in documentation projects
This guide shows you how to add redirects with practical examples.
- Best practices for linking to your documentation
Information and tips about creating and handling external references.
- How to deprecate content
A guide to deprecating features and other topics in a documentation.
Built-in redirects
This section explains the redirects that are automatically active for all projects and how they are useful. Built-in redirects are especially useful for creating and sharing incoming links, which is discussed in depth in Best practices for linking to your documentation.
Page redirects at /page/
You can link to a specific page and have it redirect to your default version,
allowing you to create links on external sources that are always up to date.
This is done with the /page/
URL prefix.
For instance, you can reach the page you are reading now by going to https://docs.readthedocs.io/page/guides/best-practice/links.html.
Another way to handle this is the latest
version.
You can set your latest
version to a specific version and just always link to latest
.
You can reach this page by going to https://docs.readthedocs.io/en/latest/guides/best-practice/links.html.
Root URL redirect at /
A link to the root of your documentation (<slug>.readthedocs.io/
) will redirect to the default version,
as set in your project settings.
This works for both readthedocs.io (Read the Docs Community), readthedocs-hosted.com (Read the Docs for Business), and custom domains.
For example:
docs.readthedocs.io -> docs.readthedocs.io/en/stable/
Warning
You cannot use the root redirect to reference specific pages.
/
only redirects to the default version,
whereas /some/page.html
will not redirect to /en/latest/some/page.html
.
Instead, use Page redirects at /page/.
You can choose which is the default version for Read the Docs to display. This usually corresponds to the most recent official release from your project.
Root language redirect at /<lang>/
A link to the root language of your documentation (<slug>.readthedocs.io/en/
)
will redirect to the default version of that language.
For example, accessing the English language of the project will redirect you to the its default version (stable
):
https://docs.readthedocs.io/en/ -> https://docs.readthedocs.io/en/stable/
Shortlink with https://<slug>.rtfd.io
Links to rtfd.io
are treated the same way as readthedocs.io
.
They are intended to be easy and short for people to type.
You can reach these docs at https://docs.rtfd.io.
User-defined redirects
Page redirects
Page Redirects let you redirect a page across all versions of your documentation.
Note
Since pages redirects apply to all versions,
From URL
doesn’t need to include the /<language>/<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 take into account the full URL (including language and version), allowing you to create a redirect for a specific version or language of your documentation.
Clean/HTML URLs redirects
If you decide to change the style of the URLs of your documentation, you can use Clean URL to HTML or HTML to clean URL redirects to redirect users to the new URL style.
For example, if a previous page was at /en/latest/install.html
,
and now is served at /en/latest/install/
, or vice versa,
users will be redirected to the new URL.
Limitations and observations
Read the Docs Community users are limited to 100 redirects per project, and Read the Docs for Business users have a number of redirects limited by their plan.
By default, redirects only apply on pages that don’t exist. Forced redirects allow you to apply redirects on existing pages.
Redirects aren’t applied on previews of pull requests. You should treat these domains as ephemeral and not rely on them for user-facing content.
You can redirect to URLs outside Read the Docs, just include the protocol in
To URL
, e.ghttps://example.com
.A wildcard can be used at the end of
From URL
(suffix wildcard) to redirect all pages matching a prefix. Prefix and infix wildcards are not supported.If a wildcard is used in
From URL
, the part of the URL that matches the wildcard can be used inTo URL
with the:splat
placeholder.Redirects without a wildcard match paths with or without a trailing slash, e.g.
/install
matches/install
and/install/
.The order of redirects matters. If multiple redirects match the same URL, the first one will be applied. The order of redirects can be changed from your project’s dashboard.
If an infinite redirect is detected, a 404 error will be returned, and no other redirects will be applied.
Examples
Redirecting a page
Say you move the example.html
page into a subdirectory of examples: examples/intro.html
.
You can create a redirect with the following configuration:
Type: Page Redirect
From URL: /example.html
To URL: /examples/intro.html
Users will now be redirected:
From
https://docs.example.com/en/latest/example.html
tohttps://docs.example.com/en/latest/examples/intro.html
.From
https://docs.example.com/en/stable/example.html
tohttps://docs.example.com/en/stable/examples/intro.html
.
If you want this redirect to apply to a specific version of your documentation, you can create a redirect with the following configuration:
Type: Exact Redirect
From URL: /en/latest/example.html
To URL: /en/latest/examples/intro.html
Note
Use the desired version and language instead of latest
and en
.
Redirecting a directory
Say you rename the /api/
directory to /api/v1/
.
Instead of creating a redirect for each page in the directory,
you can use a wildcard to redirect all pages in that directory:
Type: Page Redirect
From URL: /api/*
To URL: /api/v1/:splat
Users will now be redirected:
From
https://docs.example.com/en/latest/api/
tohttps://docs.example.com/en/latest/api/v1/
.From
https://docs.example.com/en/latest/api/projects.html
tohttps://docs.example.com/en/latest/api/v1/projects.html
.
If you want this redirect to apply to a specific version of your documentation, you can create a redirect with the following configuration:
Type: Exact Redirect
From URL: /en/latest/api/*
To URL: /en/latest/api/v1/:splat
Note
Use the desired version and language instead of latest
and en
.
Redirecting a directory to a single page
Say you put the contents of the /examples/
directory into a single page at /examples.html
.
You can use a wildcard to redirect all pages in that directory to the new page:
Type: Page Redirect
From URL: /examples/*
To URL: /examples.html
Users will now be redirected:
From
https://docs.example.com/en/latest/examples/
tohttps://docs.example.com/en/latest/examples.html
.From
https://docs.example.com/en/latest/examples/intro.html
tohttps://docs.example.com/en/latest/examples.html
.
If you want this redirect to apply to a specific version of your documentation, you can create a redirect with the following configuration:
Type: Exact Redirect
From URL: /en/latest/examples/*
To URL: /en/latest/examples.html
Note
Use the desired version and language instead of latest
and en
.
Redirecting a page to the latest version
Say you want your users to always be redirected to the latest version of a page,
your security policy (/security.html
) for example.
You can use a wildcard with a forced redirect to redirect all versions of that page to the latest version:
Type: Page Redirect
From URL: /security.html
To URL: https://docs.example.com/en/latest/security.html
Force Redirect: True
Users will now be redirected:
From
https://docs.example.com/en/v1.0/security.html
tohttps://docs.example.com/en/latest/security.html
.From
https://docs.example.com/en/v2.5/security.html
tohttps://docs.example.com/en/latest/security.html
.
Note
To URL
includes the domain, this is required,
otherwise the redirect will be relative to the current version,
resulting in a redirect to https://docs.example.com/en/v1.0/en/latest/security.html
.
Redirecting an old version to a new one
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/
.
You can use an exact redirect to do so:
Type: Exact Redirect
From URL: /en/2.0/*
To URL: /en/3.0/:splat
Users will now be redirected:
From
https://docs.example.com/en/2.0/dev/install.html
tohttps://docs.example.com/en/3.0/dev/install.html
.
Note
For this redirect to work, your old version must be disabled,
if the version is still active, you can use the Force Redirect
option.
Creating a shortlink
Say you want to redirect https://docs.example.com/security
to https://docs.example.com/en/latest/security.html
,
so it’s easier to share the link to the page.
You can create a redirect with the following configuration:
Type: Exact Redirect
From URL: /security
To URL: /en/latest/security.html
Users will now be redirected:
From
https://docs.example.com/security
(no trailing slash) tohttps://docs.example.com/en/latest/security.html
.From
https://docs.example.com/security/
(trailing slash) tohttps://docs.example.com/en/latest/security.html
.
Migrating your docs to Read the Docs
Say that you previously had your docs hosted at https://docs.example.com/dev/
,
and choose to migrate to Read the Docs with support for multiple versions and translations.
Your documentation will now be served at https://docs.example.com/en/latest/
,
but your users may have bookmarks saved with the old URL structure, for example https://docs.example.com/dev/install.html
.
You can use an exact redirect with a wildcard to redirect all pages from the old URL structure to the new one:
Type: Exact Redirect
From URL: /dev/*
To URL: /en/latest/:splat
Users will now be redirected:
From
https://docs.example.com/dev/install.html
tohttps://docs.example.com/en/latest/install.html
.
Migrating your documentation to another domain
You can use an exact redirect with the force option to migrate your documentation to another domain, for example:
Type: Exact Redirect
From URL: /*
To URL: https://newdocs.example.com/:splat
Force Redirect: True
Users will now be redirected:
From
https://docs.example.com/en/latest/install.html
tohttps://newdocs.example.com/en/latest/install.html
.
Changing your Sphinx builder from html
to dirhtml
When you change your Sphinx builder from html
to dirhtml
,
all your URLs will change from /page.html
to /page/
.
You can create a redirect of type HTML to clean URL
to redirect all your old URLs to the new style.