Canonical URLs

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”).

  • The canonical custom domain if you have one, otherwise the default subdomain will be used.

For example, if you have a project named example-docs with a custom domain https://docs.example.com, then your documentation will be served at https://example-docs.readthedocs.io and https://docs.example.com. 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 https://example-docs.readthedocs.io/en/latest/, it will know that it should really point at https://docs.example.com/en/latest/, thus avoiding duplicating the content.

Note

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.

Implementation

The canonical URL is set in HTML with a link element. For example, this page has a canonical URL of:

<link rel="canonical" href="https://docs.readthedocs.io/en/stable/canonical-urls.html" />

Sphinx

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.

Mkdocs

For MkDocs this isn’t done automatically, but you can use the site_url setting to set a similar value.

Warning

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.