A canonical URL allows you to specify the preferred version of a web page to prevent duplicated content. They are mainly used by search engines to link users to the correct version and domain of your documentation.
If canonical URL’s 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.
How Read the Docs generates canonical URLs¶
The canonical URL takes into account:
The default version of your project (usually “latest” or “stable”).
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.
The canonical URL is set in HTML with a
For example, this page has a canonical URL of:
<link rel="canonical" href="https://docs.readthedocs.io/en/stable/canonical-urls.html" />
If you are using Sphinx,
Read the Docs will set the value of the html_baseurl setting (if isn’t already set) to your canonical domain.
If you already have
html_baseurl set, you need to ensure that the value is correct.
If you change your default version or canonical domain, you’ll need to re-build all your versions in order to update their canonical URL to the new one.