Version switcher lately never succeeds at staying on the same page #7160

ilyagr · 2024-05-07T00:07:48Z

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)

Go to https://martinvonz.github.io/jj/prerelease/config/
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 a628293, specifically the changes to the fetchSitemap and extract functions.

After that commit, something clearly wrong is happening in:

mkdocs-material/src/templates/assets/javascripts/integrations/version/index.ts

Lines 135 to 139 in c1336ae

 const location = getLocation() 

 const path = location.href.replace(config.base, "") 

 return sitemap.has(path.split("#")[0]) 

 ? new URL(`../${version}/${path}`, config.base) 

 : new URL(url)

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.

Reproduction

See description

Steps to reproduce

See description

Browser

Firefox 125.0.3 on Mac OS Sonoma

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.

The text was updated successfully, but these errors were encountered:

I'm hoping this will fix version switching. squidfunk/mkdocs-material#7160

squidfunk · 2024-05-07T04:51:13Z

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 · 2024-05-07T05:11:20Z

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

ilyagr · 2024-05-07T05:12:57Z

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 · 2024-05-07T05:14:32Z

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 · 2024-05-07T05:21:53Z

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 · 2024-05-07T05:24:47Z

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.

I'm hoping this will fix version switching. squidfunk/mkdocs-material#7160

ilyagr · 2024-05-07T21:42:53Z

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 · 2024-05-08T03:56:15Z

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

Why switching version from CF216 to any other versions does not retain the same page? #6809 (reply in thread)

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 · 2024-05-08T05:32:30Z

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 · 2024-05-08T05:36:09Z

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 · 2024-05-08T05:38:01Z

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 · 2024-05-08T06:10:20Z

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

squidfunk · 2024-05-12T12:21:47Z

Fixed in ceacfe5. 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 · 2024-05-12T12:34:03Z

Released as part of 9.5.22.

ilyagr · 2024-05-12T21:03:22Z

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!

squidfunk/mkdocs-material#7160 is supposed to be fixed now. I will double-check that the version switcher still works after this commit. The functionality is a bit brittle, so it's hard to test locally before merging this. We do want to upgrade, since this will allow us to upgrade to MkDocs 1.6, which has a nice feature of disallowing links to broken document section (beyond just checking for links to non-existent files). I carefully avoided unnecessary upgrades in this commit, but we should also run `poetry update` shortly, once we check this works properly.

squidfunk/mkdocs-material#7160 is supposed to be fixed now. I will double-check that the version switcher still works after this commit. The functionality is a bit brittle, so it's hard to test locally before merging this. We do want to upgrade, since this allows us (and seems to also require us) to upgrade to MkDocs 1.6, which has a nice feature of disallowing links to broken document section (beyond just checking for links to non-existent files). I carefully avoided unnecessary upgrades in this commit, but we should also run `poetry update` shortly, once we check this works properly. Also, the feature of MkDocs 1.6 I mentioned needs enabling.

squidfunk/mkdocs-material#7160 is supposed to be fixed now. I will double-check that the version switcher still works after this commit. The functionality is a bit brittle, so it's hard to test locally before merging this. We do want to upgrade, since this allows us (and seems to also require us) to upgrade to MkDocs 1.6, which has a nice feature of disallowing links to broken document section (beyond just checking for links to non-existent files). I carefully avoided unnecessary upgrades in this commit, but we should also run `poetry update` shortly, once we check this works properly. Also, the feature of MkDocs 1.6 I mentioned needs enabling. Finally, I plan to change version specifiers from Poetry's `^5.6.22` syntax to more plain inequalities, since I keep forgetting what the former syntax means. I started with this commit.

squidfunk/mkdocs-material#7160 is supposed to be fixed now. I will double-check that the version switcher still works after this commit. This only affects the version switcher from "prerelease" to other versions.. The functionality is a bit brittle, so it's hard to test locally before merging this. We do want to upgrade, since this allows us (and seems to also require us) to upgrade to MkDocs 1.6, which has a nice feature of disallowing links to broken document section (beyond just checking for links to non-existent files). I carefully avoided unnecessary upgrades in this commit, but we should also run `poetry update` shortly, once we check this works properly. Also, the feature of MkDocs 1.6 I mentioned needs enabling. Finally, I plan to change version specifiers from Poetry's `^5.6.22` syntax to more plain inequalities, since I keep forgetting what the former syntax means. I started with this commit.

squidfunk/mkdocs-material#7160 is supposed to be fixed now. I will double-check that the version switcher still works after this commit. This only affects the version switcher from "prerelease" to other versions.. The functionality is a bit brittle, so it's hard to test locally before merging this. We do want to upgrade, since this allows us (and seems to also require us) to upgrade to MkDocs 1.6, which has a nice feature of disallowing links to broken document section (beyond just checking for links to non-existent files). I carefully avoided unnecessary upgrades in this commit, but we should also run `poetry update` shortly, once we check this works properly. Also, the feature of MkDocs 1.6 I mentioned needs enabling. Finally, I plan to change version specifiers from Poetry's `^5.6.22` syntax to more plain inequalities, since I keep forgetting what the former syntax means. I started with this commit. (I was surprised MkDocs was allowed to be upgraded with the ^1.5.2 spec. I now suspect that what I previously thought it should mean is expressed as ~1.5.2, but inequalities are clearer).

squidfunk/mkdocs-material#7160 is supposed to be fixed now. I will double-check that the version switcher still works after this commit. This only affects the version switcher from "prerelease" to other versions.. The functionality is a bit brittle, so it's hard to test locally before merging this. We do want to upgrade, since this allows us (and seems to also require us) to upgrade to MkDocs 1.6, which has a nice feature of disallowing links to broken document section (beyond just checking for links to non-existent files). I carefully avoided unnecessary upgrades in this commit, but we should also run `poetry update` shortly, once we check this works properly. Also, the feature of MkDocs 1.6 I mentioned needs enabling. Finally, I plan to change version specifiers from Poetry's `^5.6.22` syntax to more plain inequalities, since I keep forgetting what the former syntax means. I started with this commit. (I was surprised MkDocs was allowed to be upgraded to `1.6` with the `^1.5.2` spec. I now suspect that what I previously thought it should mean is expressed as `~1.5.2`, but inequalities are clearer).

ilyagr mentioned this issue May 7, 2024

docs: downgrade mkdocs-material martinvonz/jj#3635

Merged

4 tasks

ilyagr added a commit to ilyagr/jj that referenced this issue May 7, 2024

docs: downgrade mkdocs-material

c2cf626

I'm hoping this will fix version switching. squidfunk/mkdocs-material#7160

ilyagr changed the title ~~The functionality that tries to stay on the same page when using the version switcher is broken~~ Staying on the same page when using the version switcher is broken May 7, 2024

ilyagr changed the title ~~Staying on the same page when using the version switcher is broken~~ Staying on the same page when using the version switcher is broken lately May 7, 2024

ilyagr changed the title ~~Staying on the same page when using the version switcher is broken lately~~ Version switcher lately never succeeds at staying on the same page May 7, 2024

squidfunk added the bug Issue reports a bug label May 7, 2024

ilyagr added a commit to martinvonz/jj that referenced this issue May 7, 2024

docs: downgrade mkdocs-material

60ee462

I'm hoping this will fix version switching. squidfunk/mkdocs-material#7160

ilyagr mentioned this issue May 7, 2024

Docs (direct website push): fix version switcher by recompiling docs for past versions with older mkdocs-material martinvonz/jj#3643

Merged

squidfunk added the needs reproduction Issue lacks a minimal reproduction .zip file label May 8, 2024

squidfunk added resolved Issue is resolved, yet unreleased if open and removed needs reproduction Issue lacks a minimal reproduction .zip file labels May 12, 2024

squidfunk closed this as completed May 12, 2024

ilyagr mentioned this issue May 12, 2024

docs: try upgrading mkdocs-material again martinvonz/jj#3676

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Version switcher lately never succeeds at staying on the same page #7160

Version switcher lately never succeeds at staying on the same page #7160

ilyagr commented May 7, 2024 •

edited

squidfunk commented May 7, 2024

ilyagr commented May 7, 2024

ilyagr commented May 7, 2024

ilyagr commented May 7, 2024

ilyagr commented May 7, 2024

squidfunk commented May 7, 2024

ilyagr commented May 7, 2024

kamilkrzyskow commented May 8, 2024

squidfunk commented May 8, 2024

ilyagr commented May 8, 2024

ilyagr commented May 8, 2024

squidfunk commented May 8, 2024

squidfunk commented May 12, 2024

squidfunk commented May 12, 2024

ilyagr commented May 12, 2024 •

edited

Version switcher lately never succeeds at staying on the same page #7160

Version switcher lately never succeeds at staying on the same page #7160

Comments

ilyagr commented May 7, 2024 • edited

Bug description

Context

Related links

Reproduction

Steps to reproduce

Browser

Before submitting

squidfunk commented May 7, 2024

ilyagr commented May 7, 2024

ilyagr commented May 7, 2024

ilyagr commented May 7, 2024

ilyagr commented May 7, 2024

squidfunk commented May 7, 2024

ilyagr commented May 7, 2024

kamilkrzyskow commented May 8, 2024

squidfunk commented May 8, 2024

ilyagr commented May 8, 2024

ilyagr commented May 8, 2024

squidfunk commented May 8, 2024

squidfunk commented May 12, 2024

squidfunk commented May 12, 2024

ilyagr commented May 12, 2024 • edited

ilyagr commented May 7, 2024 •

edited

ilyagr commented May 12, 2024 •

edited