Version switcher lately never succeeds at staying on the same page

[ilyagr]

Bug description

(Update: This reproduction no longer works -- or rather, there is no bug, everything works as intended -- after I downgraded that website to be compiled with the old 9.5.4 version of mkdocs-material. It should be possible to reproduce this with https://github.com/squidfunk/mkdocs-material-example-versioning, but it requires recompiling that website with a recent version of mkdocs-material)

1. Go to https://martinvonz.github.io/jj/prerelease/config/
2. Use the version switcher to switch to the "v0.17.0" version

Observed: you end up at https://martinvonz.github.io/jj/v0.17.0/

Desired behavior: you should end up at https://martinvonz.github.io/jj/v0.17.0/config/

Context

I can flesh out this bug report if desired, but I believe I found the likely culprit to be https://github.com/squidfunk/mkdocs-material/commit/a6282931efa2a79665333d41e50bc532367b671a, specifically the changes to the fetchSitemap and extract functions.

After that commit, something clearly wrong is happening in:

https://github.com/squidfunk/mkdocs-material/blob/c1336ae0f598a47828c44073fb6491f622280e0d/src/templates/assets/javascripts/integrations/version/index.ts#L135-L139

As I debug, with the reproduction I describe below, I find that sitemap is a Map object with value (as abbreviated by the Firefox debugger):

Map(31) {
"https://martinvonz.github.io/jj/v0.17.0/" → (1) [...],
"https://martinvonz.github.io/jj/v0.17.0/FAQ/" → (1) [...],
"https://martinvonz.github.io/jj/v0.17.0/branches/" → (1) [...],
... }

​```

Meanwhile, path.split("#")[0] has the value "config/". So, the operation sitemap.has(path.split("#")[0]) cannot evaluate to true.

Related links

https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/?h=version#stay-on-the-same-page-when-switching-versions

Reproduction

See description

Steps to reproduce

See description

Browser

Firefox 125.0.3 on Mac OS Sonoma

Before submitting

• [X] I have read and followed the bug reporting guidelines.
• [X] 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. Since you already digged into possible causes, would you like to create a PR? Happy to collaborate in gravitating towards a solution, and I agree that it's likely related to the latest refactoring.

[ilyagr]

What's a good way to set up a dev environment for the theme, especially one where I can use the version switcher?

[ilyagr]

I was hoping https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md would link to an explanation, but it seems to link to nonexistent pages.

[ilyagr]

Ah, I found https://squidfunk.github.io/mkdocs-material/customization/#environment-setup. I'll let you know if I have questions after reading that.

[ilyagr]

Setting up something with a version switcher seems tricky. I guess I can follow the instructions and then try to make my own project (with my documentation, managed with Poetry) depend on mkdocs-material from the git cloned directory. Then I can try to run mike and see whether things work.

[squidfunk]

Jup, correct. Let me know if you have troubles. I think you can use mike serve, or deploy for testing on a new repo. I recommend to just use pip and install the bare minimum. You could also work off our versioning example (that was built with a prior version), and work with that.

[ilyagr]

It does seem that downgrading mkdocs-material to 9.5.4 helps. Unfortunately, that version claims to be incompatible with the new MkDocs 1.6.

I will hopefully get to working on fixing this... at some point.

[kamilkrzyskow]

Perhaps you could try checking out my hunch about the URLs that are stored in the sitemap:

• https://github.com/squidfunk/mkdocs-material/discussions/6809#discussioncomment-8551776

However, I see that your site has different URLs in the sitemap, so the hunch is likely incorrect 🤔 It properly stores the current /version/ in the URLs, instead of reusing a static one.

This "shadow" issue has been here for quite some time, good that someone is willing to properly debug it 💪

[squidfunk]

Thanks @ilyagr and @kamilkrzyskow! I'll tag this issue with "needs reproduction", because none was provided. To go forward, we definitely need a minimal reproduction, because we need something to test a potential fix against ☺️ Also, as said, if somebody makes progress, please open a PR. I'm happy to assist. If nobody is up to it, I'll try to find some time asap.

[ilyagr]

One way to create a reproduction is to add a GitHub action to https://github.com/squidfunk/mkdocs-material-example-versioning to compile a "nightly" version of its docs nightly. That would show the problem, among with any potential future problems. This is on the list of my "might get to at some point" things to do.

[ilyagr]

The procedure in https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/ is not very good for this case, since it doesn't involve mike. Without mike, compiled docs don't even include a visible version switcher.

[squidfunk]

The reproduction still allows us to run mike with some instructions to observe the issue.

[squidfunk]

Fixed in ceacfe5a2. This turned out to be a regression in 9.5.5 where we refactored the sitemap loading logic, which was necessary to get instant navigation right. My testing shows that the issue is fixed now, and we redeployed our versioning example which shows that it works.

[squidfunk]

Released as part of 9.5.22.

[ilyagr]

Thank you very much, I appreciate it! I'll try it out in a bit, will let you know if it fails for me, but it looks like it should be fine.

I was thinking of making the functionality a bit more robust by parsing the UR in the sitemap, ignoring the domain name, and only looking at the directory path. Then, for example, the version switcher from https://squidfunk.github.io/mkdocs-material-example-versioning/latest/ would work if I deployed it at https://ilyagr.github.io/mkdocs-material-example-versioning/latest/ without recompiling. I was then hoping for maybe eventually adjusting the behavior of mike serve so that the version switcher worked there too.

If that sounds at all reasonable, you might see a PR from me yet, or feel free to borrow the idea and run with it.

Thank you again!

[ilyagr]

If you still see this kind of bug, you might actually be experiencing the closely related https://github.com/squidfunk/mkdocs-material/issues/7226.