Docs for multiple library versions

[cspotcode]

The Discord discussion included some tricky problems related to semver rendering docs for multiple versions of the same library. I'm creating this issue to discuss.

Some of the issues discussed:

• If libA depends on libB ^4.3.0, and we rendered docs for libB 4.3.10
  • the libA docs should link to the libB docs for 4.3.10
• if libB releases a new version 4.4.0
  • the old libB docs should be replaced with a new render of 4.4.0
  • libA docs should link to the new lib 4.4.0, because ^4.3.0 is satisfied by 4.4.0
  • libA docs should not need to be re-rendered to achieve the bullet point above
• if libC depends on libB 3, we must maintain 2x renders of libB: 4.x.x and 3.x.x

I wonder, can we handle some of these issues with runtime link replacement? Or with server-side redirects?

For example, suppose libA is rendered to link to URL .../libB/^4.3.0 The semver range is encoded in the URL.
Browser-side JS replaces the links when the page loads. This browser-side JS checks a manifest file to see which versions of libB have been rendered. It finds the newest one that is compatible with the semver range, and rewrites all anchor hrefs to point to it: .../libB/4.4.0

Can entire directories be server-side redirected using Github Pages or another hosting solution? (Related discussion: #2)
If so, we could eliminate the need for client-side logic.

[cspotcode]

I found this trick created for SPAs, but it would also be useful for us, even though we are not creating an SPA:
https://github.com/rafgraph/spa-github-pages

Github Pages supports a custom 404 page. Links to missing pages will display the 404. We can put client-side JS in the 404 page which reads the encoded semver range from the URL and redirects to the appropriate documentation.

[keithlayne]

Yep. I couldn't think of a simple way to handle that on the client, but custom 404 fits well.