What is the recommended approach on GitHub to organizing documentation when working on a new version that represents a major rewrite?
In my project pg-promise I rely on jsDoc to generate all the documentation, and then publish it into gh-pages, as one usually does.
And while working on a new version that's a major rewrite and a documentation change, what is the best approach to making the new/unreleased documentation available? -
1. Should I simply create a separate repository just for the sake of publishing updated documentation there?
2. Should I use an external hosting/solution altogether?
3. Is there any GitHub feature that will let me publish more than one documentation version?
Thanks in advance!
This is feasible using Github Actions along with a static site generator (SSG) of your choice such as VuePress, Gatsby, Jekyll etc.
In its simplest form, create a GH action to generate the static site folder of the branch/release, then push the folder to corresponding folder in the branch pointed to by GH pages, say gh-pages. One of the branches/releases should be pushed to root. GitHub Pages Deploy Action can be helpful. Add a dropdown list of versions to your static website pointing to the matching folder.
Example: