k8gb
k8gb copied to clipboard
k8gb-io
Add versioning to k8gb.io documentation
As our releasing cadence increases, and we bring more breaking changes, it might be useful to have a versioning system for our documentation.
This might help us to keep track of what's new in each release, especially when it comes to k8gb configuration values.
P.S. This might require changing of Jekyll theme to something that supports versioning, or changing to some other static web-page authoring framework, which has that versioning support built-in, like Hugo
Assignees: Labels: documentation
there is a docsy hugo template used by a lot of cncf projects: https://www.docsy.dev/docs/examples/ and also by k8s itself
I think the version support is not there in the template or hugo itself.. well it can be done using the directories, like:
-
content/en/docs/v0.0.1/something.md -
content/en/docs/v0.0.2/something.md
But this is not a good approach, imho. What I've seen is this:
- have the main template for the landing page in 1 branch (be it
gh-pagesor anything else) - have the version specific docs stored in a separate branch using some template, like
v0.x-docs(often this scheme corresponds with the strategy when breaking changes are introduced -> need for another parallel docs) - use the netlify feature for this: https://docs.netlify.com/domains-https/custom-domains/multiple-domains/#branch-subdomains together with auto builds
- link those versioned docs from the landing page from some combo box
examples using this approach are:
- https://www.kubeflow.org/
- https://docs.k8ssandra.io/
- https://kubernetes.io/ (check the links when switching the versions)
Found this in docsy's documentation: https://www.docsy.dev/docs/adding-content/versioning/
ah cool, yes, that looks like 4) from my description. So the combo box (/dropdown) is a built-in feature in the template, but they are not opinionated about the deployment of those versions
yep, so we can use branch subdomains for publishing and then refer to these subdomains