How to enable canonical URLs
In this guide, we introduce relevant settings for enabling canonical URLs in popular documentation frameworks.
If you need to customize the domain from which your documentation project is served, please refer to How to manage custom domains.
Sphinx
If you are using Sphinx, Read the Docs will automatically add a default value of the html_baseurl setting matching your canonical domain.
If you are using a custom html_baseurl in your conf.py,
you have to ensure that the value is correct.
This can be complex,
supporting pull request builds (which are published on a separate domain),
special branches
or if you are using subproject s or translations.
We recommend not including a html_baseurl in your conf.py,
and letting Read the Docs define it.
MkDocs
For MkDocs we do not define your canonical domain automatically, but you can use the site_url setting to set a similar value.
In your mkdocs.yml, define the following:
# Canonical URL, adjust as need with respect to your slug, language,
# default branch and if you use a custom domain.
site_url: https://<slug>.readthedocs.io/en/stable/
Note that this will define the same canonical URL for all your branches and versions. According to MkDocs, defining site_url will only define the canonical URL of a website and does not affect the base URL of generated links, CSS, or Javascript files.
Note
2 known issues are currently making it impossible to use environment variables in MkDocs configuration. Once these issues are solved, it will be easier.
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.