Document `versions.json` workaround when a server doesn't automatically forward to `index.html`

[maarten-ic]

I found the version switcher does not work out-of-the box when the server where the documentation is deployed doesn't forward a request to a directory (e.g. "docs/2.0/") to the index.html in that directory (e.g. "docs/2.0/index.html"). I did find a way to make this work though, which may be nice to document for others that encounter this problem.

Instead of the regular versions.json

[
  {"version": "2.0", "title": "2.0", "aliases": ["latest"]},
  {"version": "1.0", "title": "1.0", "aliases": []},
]

I used the following

[
  {"version": "2.0/index.html#", "title": "2.0", "aliases": ["2.0", "latest"]},
  {"version": "1.0/index.html#", "title": "1.0", "aliases": ["1.0"]},
]

Since the redirect URL is built as: ${base_url}/../${version}/ (source) this will now create a link directly to the index.html page. The folder name is included in the aliases field such that the setupVersionSelector (source) can still find out which version you're looking at.

[2bndy5]

You are welcome to submit a PR to modify the doc.