A canonical URL allows you to specify the preferred version of a web page to prevent duplicated content. Here are some examples of when a canonical URL is used:
Search engines use your canonical URL to link users to the correct version and domain of your documentation.
Many popular chat clients and social media networks generate link previews, using your canonical URL as the final destination.
If canonical URLs aren’t used, it’s easy for outdated documentation to be the top search result for various pages in your documentation. This is not a perfect solution for this problem, but generally people finding outdated documentation is a big problem, and this is one of the suggested ways to solve it from search engines.
In most cases, Read the Docs will automatically generate a canonical URL for Sphinx projects. Most Sphinx users do not need to take further action.
- How to enable canonical URLs
More information on how to enable canonical URLs in your project.
How Read the Docs generates canonical URLs
The canonical URL takes the following into account:
The default version of your project (usually “latest” or “stable”).
The canonical custom domain if you have one, otherwise the default subdomain will be used.
For example, if you have a project named
with a custom domain
then your documentation will be served at
Without specifying a canonical URL, a search engine like Google will index both domains.
You’ll want to use
https://docs.example.com as your canonical domain.
This means that when Google indexes a page like
it will know that it should really point at
thus avoiding duplicating the content.
If you want your custom domain to be set as the canonical, you need to set
Canonical: This domain is the primary one where the documentation is served from in the Admin > Domains section of your project settings.
A canonical URL is automatically specified in the HTML output with a
For instance, regardless of whether you are viewing this page on
the following HTML header data will be present:
<link rel="canonical" href="https://docs.readthedocs.io/en/stable/canonical-urls.html" />