Version switcher fails to stay on the same page when `canonical_version` is set in mike

[kevinh-hcl]

Context

We are using mkdocs-material together with mike for our documentation.

To improve SEO we set the canonical_version in mike. This sets the rel="canonical" link on every page and also leads to the sitemap.xml in each version using the canonical links (with latest). This seems to be the expected way of handling canonical URLs according to Google Search Central and others.

Bug description

When switching from a sub page of any version to a version that was built with the canonical_version you get redirected to the homepage of the version. The expected behaviour would be to stay on the same sub page, but in a different version.

From what I can see this is probably due to mkdocs-material using the sitemap of the version to determine if a sub page is available in that version. Since the sitemap always uses the canonical_version instead of the actual version, the page is not found and it falls back to the homepage.

Related links

Related documentation

• Reporting a bug
• Setting up versioning - Stay on the same page when switching versions

Pointer from a previous discussion

• kamilkrzyskow seems to have the right idea in this discussion about the latest in all sitemap.xml

Related mike documentation and code

• mike: configuration options
• mike: building site_url from canonical_version

Reproduction in a fork from mkdocs-material-example-versioning

• Setting canonical_version
• Github Pages Version 0.5 (with canonical_version). You can switch FROM this versions to others just fine
• Github Pages Version 0.4. Switch TO 0.5 and get redirected to the homepage
• 0.5 sitemap
• 0.4 sitemap

Reproduction

9.5.25-version-switcher-canonical.zip

Steps to reproduce

1. unzip 9.5.25-version-switcher-canonical.zip and navigate to the extracted folder
2. (Optional: I had to remove the venv due to the size limitation in the .zip upload. Please follow https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/#environment to create a venv and activate it)
3. Install the dependencies using pip install --upgrade --force-reinstall mike==2.1.1 mkdocs-material==9.5.25 mkdocs==1.6.0
4. In mkdocs.yml remove the - info from the plugins section and save the changes
5. Deploy a first version using mike deploy canonical
6. In mkdocs.yml remove the canonical_version: latest from mike in the plugins section and save the changes
7. Deploy a second version using mike deploy no-canonical latest
8. Serve the documentation locally using mike serve

Working as expected:

1. Open http://localhost:8000/canonical/subpage/
2. Switch to the no-canonical version
3. The version shows the correct page
4. (Optional: check http://localhost:8000/no-canonical/sitemap.xml of the target version)

Not working as expected:

1. Open http://localhost:8000/no-canonical/subpage/
2. Switch to the canonical version
3. Redirected to the homepage
4. (Optional: check http://localhost:8000/canonical/sitemap.xml of the target version)

Browser

Chrome

Before submitting

• I have read and followed the bug reporting guidelines.
• I have attached links to the documentation, and possibly related issues and discussions.
• I assure that I have removed all customizations before submitting this bug report.
• I have attached a .zip file with a minimal reproduction using the built-in info plugin.

[squidfunk]

Thanks for reporting and the very detailed explanations. Yes, it sounds like a currently unhandled combination of configuration settings when using mike. I'm not sure it's a bug, since we don't advertise the canonical_version setting anywhere in our documentation, so I'll tag this as an chance request. Since you have already invested some time into tracking down the cause, would you like to work on this in a PR? Happy to collaborate. Shouldn't be too hard to support ☺️

[kevinh-hcl]

Thank you. I drafted a first idea of how this could be handled in #7227. Any feedback is appreciated

[squidfunk]

Thanks for the PR! Please give me some time to check it out and give it a spin.

[ilyagr]

I'm trying an alternative approach to fixing this in #7350. That approach should also make the version switcher work correctly with mike serve or if the website is published somewhere other than at site_url again.

I also set up some unit tests to stay sane while changing this behavior, hence the 6 commits.