search

bep / docuapi

Beautiful multilingual API documentation theme for Hugo
https://docuapi.netlify.app/
Other
750 stars 200 forks source link

Add versioning to the left hand-side menu #19

Open jmineraud opened 5 years ago

jmineraud commented 5 years ago

Hi, similarly to the languages (in fact, in addition to the languages), it would be cool to have the versioning of the documentation. Any ideas on how to enable this ?

eine commented 4 years ago

I this is difficult because not all the information is available when you build a single version. Say you have versions A and B. You build both of them to a subdir, both with a template that accepts a list of strings (["A", "B"]) and displays a drop-down menu (where each item points to a subdir). Then, you upload it to say GitHub Pages. Now you need to build a new version, C. You build it with argument ["A", "B", "C"], and upload it to subdir C in the target gh-pages branch. As a result, it will be possible to go from version C to either A or B, but none of these will be aware of C.

A possible workaround is to rebuild all the versions when a new one is added to the list. However, this is not desirable because each version might require a specific version of hugo and/or the theme.

A different solution is to use a JSON file that contains an updated list of available versions and a some Javascript that generates a menu dynamically. When a new version is added, the JSON file needs to be modified only. This approach is used in https://github.com/buildthedocs/sphinx_btd_theme/blob/24f6805417e2c127f6ffa371906f7cbc95d7c4d2/src/theme.js#L213-L232. The advantage is that, when the JSON file is not found (or JS does not work), the version is shown as a simple element (instead of a menu).