Version selector for other provider than mike

[agaudreault]

I started to use this project to host my documentation, but I am trying to figure out how to have a version selector. The documentation mention mike, but from what I read, it is only available for github pages.

I was looking at the kubernetes and argo-cd documentation https://argo-cd.readthedocs.io/ and they have a nice version selector. However, it queries a readthedocs API to get the version info.

Would it be possible to have another version.provider ?

An idea would be to have the version information in a json file somewhere that could be queried and could be configurable. Then if the current version defined in the config is different than the latest version in the remote config file, the banner could be displayed.

version:
  provider: json
  index: "https://my.domain/versions.json"
  current: v4 

{
    "latest": "v4",
    "versions": {
        "v1": "https://my.domain/path/v1",
        "v2": "https://my.domain/path/v2",
        "v3": "https://my.domain/path/v3",
        "v4": "https://my.domain/"
    }
}

I am not very good in web/js but I will try to do that with extra_javascript. If you know of a better/easier solution, please let me know 🙏

[squidfunk]

Please see #3128 (comment) and #3128 (comment). Also, for "not latest version" warning, see the documentation.

[agaudreault]

I was able to use the json format for mike https://github.com/squidfunk/mkdocs-material-example-versioning/blob/gh-pages/versions.json and build one manually.

I had to change my deployment pattern to make sure my version were deployed in the same folder with the versions.json at the root

path
├── v1
│   └── index.html
├── v2
│   └── index.html
├── v3
│   └── index.html
├── v4
│   └── index.html
└── versions.json

versions.json

[
  { "version": "v4", "title": "v4", "aliases": ["latest"] },
  { "version": "v3", "title": "v3", "aliases": [] },
  { "version": "v2", "title": "v2", "aliases": [] },
  { "version": "v1", "title": "v1", "aliases": [] }
]

Thanks :)

[hynek]

@agaudreault-jive would you mind to share how you achieved that? I've also generated my own versions.json file and it works great locally, but when running from RTD, mkdocs-material can't find it, because it's looking for /en/versions.json instead of /en/latest/versions.json.

I've spent a good time perusing https://argo-cd.readthedocs.io/ and its repo but there just is no versions.json anywhere and I can't find any logic that seems related.

The location where mkdocs-material looks for it appears to be hard-coded too:

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

Line 76 in a261130

new URL("../versions.json", config.base)

I've even tried using your rather old version pins, but none of it helps.

Please, what's your secret? 😅

[agaudreault]

Hmmm actually I switched to

[
  { "version": "latest", "title": "v4", "aliases": ["latest"] },
  { "version": "v3", "title": "v3", "aliases": [] },
  { "version": "v2", "title": "v2", "aliases": [] },
  { "version": "v1", "title": "v1", "aliases": [] }
]

I also have mike configured in the mkdocs.yaml

extra:
  version:
    provider: 'mike' 

When I deploy, I always deploy my assets to path/<VERSION>/* and path/latest/*, then I deploy the file path/versions.json.

path
├── v1
│   └── index.html
├── v2
│   └── index.html
├── v3
│   └── index.html
├── v4
│   └── index.html
├── latest
│   └── index.html
└── versions.json

I deploy to the 2 locations because I have an nginx that will update the default location to latest if a user does not specify one, and I did not want to have to update my nginx config if there is a new version.

  location = / {
    return 301 https://$host/latest/;
  }

So I hope that gives you enough information

[hynek]

Ah OK so you're somehow deploying RTD yourself? I was wondering, because argo-cd.readthedocs.io points to a RTD IP address.

Anyhow I got it solved, after RTD fixed a redirect bug, so for whoever comes here by Google like I did, the trick is to create a versions.json (I use https://github.com/hynek/doc2dash/blob/main/docs/update-rtd-versions.py) and then in the RTD project view go to Admin → Redirects and create an "Exact Redirect" from /en/versions.json to /en/latest/versions.json.