Document how to support multi versions for docs using environments
Problem to solve
There is a need to hold multiple docs sites in order to serve different customers that use different versions.
Any user that wishes to old several versions of a website/documentation per version.
Use our existing CI/CD and environments to hold multiple versions per release branch.
- Documentation for release 12.2 would sit under 12.2
- Documentation for release 12.3 would sit under 12.3
- Documentation for release 12.4 would sit under 12.4
- and so one.....
Here is an example of how this can be done - https://gitlab.com/krasio/vdocs/blob/master/.gitlab-ci.yml.
In short CI is configured in a way so that on push to master or "version" branches it will build a static site and then deploy it to the respective path. In the example above I use
rsync over SSH but it can be anything that will work for the user. There is also
on_stop job defined that will remove the files in case branch is deleted (or when run manually). The root is symlinked to the versions for the
master branch, it will be easy to make the default configurable (for example using CI variable). Each deployment also creates an environment - https://gitlab.com/krasio/vdocs/environments.
The result directory structure looks like this
1.0/ index.html -> ./master/index.html master/
- No size limitation
- Only single version is generated and deployed (
rsyncwill pick just the files that changed).
- Pretty flexible
- Users need to bring their own hosting/deployment script
- Unlike Pages, no easy to setup access control
- Unlike Pages, no Let's Encrypt integration, users should handle SSL certs and config on their own.
Another (a bit naive) approach to do this using Pages - https://gitlab.com/krasio/versioned-docs/blob/master/.gitlab-ci.yml.
On every push to the master or one of the "version" branches it will build the site for all of them and the then publish it to Pages - https://krasio.gitlab.io/versioned-docs/.
- Built in hosting/deployment that comes from Pages
- Built in access control
- Built in Let's Encrypt integration
- Will get slow when there are many versions
- Eventually will hit Pages' size limit