docs: user can select version (instead of HEAD/nightly)

[dundargoc]

trafficstars

There have been some instances where users are confused why the documentation in neovim.io doesn't work only to realize that they don't use nightly. I have a few ideas on how we could tackle this:

• Allow users to choose the version for the documentation. I think a good example of this is cmake (crazy, right?), where the documentation version is prominently shown at the top in an easy place.

• Use the latest stable in the documentation instead of nightly. This is probably easier to implement. A problem might be that nightly users might start complaining they can't find docs for nightly features.

Open to other suggestions.

[justinmk]

Use the latest stable in the documentation instead of nightly.

Not in favor. The website docs allow us to make hints and other docs available via the website search (and search engines).

Allow users to choose the version for the documentation.

This would be ideal. But the HEAD docs should stay at the current paths, because:

• avoids breaking URLs
• avoids needing to update our Algolia config

The version-specific docs could live at e.g. https://neovim.io/doc/user/v0.10/.

Edit: instead of the above, let's start by using @since annotations as much as possible, and use CSS to make those prominent, and maybe show hover info with details.

[clason]

Just adding that we are seeing increasing confusion since people look at docs (as we tell them to) and find documentation or code examples that simply won't work for them (since they use 0.10, as we tell them to).

At the very least, we should consider adding a (floating?) disclaimer at the top of the page that this documentation refers to nightly and, if in doubt, check with :help.

[justinmk]

The version-specific docs could live at e.g. https://neovim.io/doc/user/v0.10/.

Instead of this, let's double-down on the @since annotations, at least to start with. And we can make those more prominent via CSS.

[clason]

But that won't work with current "soft deprecations" which hide the documentation. (In this case, users will find no docs for them: the old ones are gone, but the new shown ones are inapplicable.)

[justinmk]

But that won't work with current "soft deprecations" which hide the documentation

They will be on deprecated.txt ?