Questions about versioning behaviour

[ajstewart]

First, thanks so much for the awesome project!

I've recently upgraded my documentation from 7.x to 8.2.1 and also implemented versioning. I have a couple of issues/questions as I'm not entirely sure if these are issues, my setup logic or intended.

---

1. Versioning switching on same page behaviour

I have a setup where I want to publish the dev docs alongside releases. So for example, lets say I have v1.0.0 which is assigned the latest alias and dev doc versions.

In 8.2.0 I see that the feature was added for non-insiders to stay on page when switching, so when experimenting I found that new pages in the dev version that are not on the v1.0.0 (as they are a new feature), when switching from dev -> v1.0.0 on such a page it 404's.

It tries to go to the page but cannot find it. Is this intended or should there be some sort of fall back option for page mis-matches between versions?

I've found that I had to downgrade to 8.1.11 so I can have the old behaviour.

---

2. Outdated Banner switching

There is the example in the docs of the following banner:

{% extends "base.html" %}

{% block outdated %}
  You're not viewing the latest version.
  <a href="{{ '../' ~ base_url }}"> 
    <strong>Click here to go to latest.</strong>
  </a>
{% endblock %}

where it is expected that <a href="{{ '../' ~ base_url }}"> will always navigate to the root and hence the default will kick in.

However, this is not always the case as some url's will require more than one step up for this to happen. You can see this behaviour on the demo versioning website here: https://squidfunk.github.io/mkdocs-material-example-versioning/0.2/

If I:

• Switch to v0.1
• Navigate to bar.
• Click the banner link.
• It takes me back to the main v0.1 page and not the expected v0.2.

This is because for some reason I'm not sure of, it's taking the full url, i.e.
https://squidfunk.github.io/mkdocs-material-example-versioning/0.1/bar/
so the logic above makes the banner link go to:
https://squidfunk.github.io/mkdocs-material-example-versioning/0.1/
Is something wrong with the base_url usage in the outdated logic?

[squidfunk]

1. Versioning switching on same page behaviour: the application will check if the current page exists in the old version, and if it does, goes to that very page. If it doesn't, the application should redirect to the top-level page, as we have no means to decide to which page we should go. Thus, if you rename a page between versions, it's a good idea to add a redirect to the old version. If this is not the behavior you're seeing, please create a new issue with a minimum reproduction.

2. Outdated Banner switching: That's shouldn't happen. It might be outdated. Please create a separate issue with a minimum reproduction.

For both topics, note that the version used to deploy the versioning example is mkdocs-material-7.1.8+insiders-2.9.2, thus quite old. I haven't managed to set aside the time to update it, so some issues might be fixed by now. This is the reason why I'm asking you to create reproductions.

[ajstewart]

Ok thanks, I will get around to trying it out on a simple example.

[ajstewart]

Just to update on this, I created a new project and tested everything out and it all worked ok. So these bugs that are on the demo website do not remain in the current version.

I'm still suffering from the problem but I've narrowed it down such that it only goes wrong when the first page landed on is the homepage (I am using instant), which I do have an override for. If I land on any other page first then the links and page redirects work. So I'm guessing it's something somewhere to do with a homepage initial load but currently I cannot find what possibly could cause it. What's even stranger is that the announcement bar message that also uses the base_url parameter seems to work fine regardless.