version selector not working

[rayaldeng]

Thank you for your efforts on this beautiful theme.

I've met some trouble utilizing the "version selector" function:

1. when using the "version info" approach, the dropdown menu would always show the top choice(not current version):

2. the aliases won't work(return 404 on static site with nginx)

3. I've also tried the "version_json" approach, which has not effect at all. Tried to put the JSON file on over the place yet won't wokring:

   • same directory with conf.py
   • parent directory of conf.py
   • also as mention in docs:

     /versions.json
     /1.0/index.html
     /2.0/index.html
     

   • and all of above places together.

Can anyone please help me with how to achieve this function?

---

environment:

sphinx==4.4.0
sphinx-immaterial==0.3.1

[2bndy5]

Fwiw, I think the version selector is only designed to work from a webserver. I'm not sure if you tried that. Hosting different versions locally didn't work for me last time I tried it.

[jbms]

There is a bug in the detection of the current version that is fixed by #54.

Two things to clarify, though:

• aliases only affects the logic for detecting the current version, it does not affect which paths can be retrieved from your web server. If you want a given path to behave as an alias, you are responsible for setting things up (e.g. with a rewrite rule on your webserver or a symlink) so that it works. The purpose of aliases is so that if the theme sees that the current URL is https://myserver/latest/, and you have configured the versions as you described, then it will determine that version 2.0 corresponds to the URLs https://myserver/2.0/ and https://myserver/latest/ and will therefore detect the version as 2.0.
• If you use the version_json approach, you are responsible for ensuring the versions.json file can be retrieved from the expected path. When you build your documentation using this theme, there is nothing that actually looks for a versions.json file and copies it to some location.

[jbms]

What @2bndy5 said as far as a web server is also true --- the way the theme currently retrieves the versions.json file is incompatible with file://. We could make it work, by converting it to a javascript file and loading it via a script tag, as is done for the search index, but I'm not sure there is a really a need for it to work with file://.

[2bndy5]

@jbms You make it sound simple... Only reason I can think of is being able to be sure my commit will work same from the server and file://. Making something that I cannot locally check/run properly can often result in messy git history. Is that a fix that might be useful upstream? Or is it exclusive to this theme?

[jbms]

The versioning in mkdocs-material is intended to be used with the mike package, so I don't think the changes I describe would be desired there, since it would require a different format for the version file.

Note that you can easily run a local web server --- e.g. npm install -g http-server and then run http-server to serve a local directory.

[2bndy5]

Python3 std libs should have a similar command, I think.

python -m http.server

I found a plugin in VSCode that puts it into a button.