Link canonical documentation to discourage search engines from linking old docs

[jfrost-mo]

What's the problem this feature will solve?

Currently when you search for a pytest feature on the web you often get linked to an old version of the documentation. This isn't ideal, as newer versions of the documentation have improvements, and its also rare that you are running the multi year old version that is often linked to.

Describe the solution you'd like

Fortunately this situation can be resolved by adding a <link rel="canonical" href="url of page in stable version"> tag onto all of the documentation pages. This can be done with sphinx by specifying the html_baseurl in the conf.py.

html_baseurl = "https://docs.pytest.org/en/stable/"

This would cause search engines indexing older versions of the page, as well as versions on other domains, such as the readthedocs.io temporary URLs, to relate all of these pages in the index, and show the canonical one in search results. After a few months the old pages should disappear from search results, and only the stable version will be shown.

Alternative Solutions

According to the documentation, ReadTheDocs should already be adding this, however it doesn't seem to be present on any pages. According to a different part of the ReadTheDocs docs, you might need to enable this for custom domains:

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.

It is worth checking if that is set first, before doing anything here.

[nicoddemus]

@jfrost-mo that's good to know, thanks a lot for detailing this.

I'm all up for it, would you like to open a PR with that?