[website] Enable documentation versioning

[elevran]

Currently, the https://clusterlink.net website holds only the the latest (main) documentation. Thus, it may intermittently diverge from the last ("officially") release code. Despite the project being in the 0.x.y state, and allow breaking changes, we should see if we can enable version based documentation to match release artifacts.
There's already Docys support for this.

[elevran]

Docsy features provide navigation between the various versions of the docs and can display an information banner on the archived sites. These mostly control the appearance of the "releases" drop down and does not help in structuring or hosting the documentation. In fact, the docsy site clearly states how you deploy the previous versions is up to you.

Netlify does not support this out of the box. They suggest hosting multiple versions using subdomains, or explicitly keeping versioned docs as a copy under the docs directory.
Nate Waddington of the CNCF has more information on these options and recommends using folders to store versions in small to medium sites. The major downsides seem to be:

• duplication (a full snapshot is copied on every version, so unchanged content is duplicated)
• search results appearing across all versions (i.e., search is not version aware and will display duplicates, see also this discussion)
• potential crowding when the number of releases is large (possible workaround: deprecate/archive and delete after some time)

This is also the recommendation in google/docsy#114 and on hugo discourse. There are numerous other references to this topic (e.g., vsoch/docsy-jekyll#23, jenkins-x/jx-docs#3114, vitessio/website#625 - the last issue is certainly worth a detailed read...) and most come to the same conclusion - use folders as the simpler method.

[elevran]

Relevant Hugo tweaks needed (e.g., shortcodes and frontmatter):

• Use relref shortcodes instead of ref actually, using relative file paths works much better than letting Hugo figure out the file/URL using either ref or relref
• use frontmatter exclude_search = true to avoid showing certain pages in search indexing (e.g., older versions). PageFind may be a better option for this down the road (e.g., this discourse discussion)
• main menu configuration might need to be set in config.toml and not defined within your file's frontmatter, otherwise hugo finds duplicates across versions
• set up redirects (e.g., remove main from path by redirecting /docs to /docs/main)

[elevran]

The use of folders requires that we define

• directory structure (e.g., support logical releases such as current, main, next in addition to version based such as v0.1.0, v0.2.12?)
• process for cutting a new documentation release (e.g., when to copy from HEAD/main/<previous> to a new versioned release)

For example:

Structure

• Only docs are versioned (blog, community, and other pages left un-versioned)
• include a main and vMAJOR.MINOR.PATCH directories (or avoid PATCH?)
  content/en/docs/
  ├─ main
  ├─ v0.8.0
  ├─ v0.7.0
• Set draft warning on main (so readers will know it is cutting edge documentation)
• may be able to emulate logical version (e.g., latest, previous, ...) by using symlinks in the file system

Process (example: release v0.2.0 from "main", v0.1.0 exists)

1. Update the local copy to upstream/main then create a new branch
   (e.g., using the new release tag, for example: "docs/v0.2.0")
   git switch -c docs/v0.2.0
2. Create a new directory under docs (e.g., docs/v0.2.0)
   mkdir content/en/docs/v0.2.0
3. Copy the contents of the most recently tagged docs directory (e.g., v0.1.0) into the new directory,
   to establish a useful baseline to diff against.
   cp -R content/en/docs/v0.1.0 content/en/docs/v0.2.0
4. Adds all copied content from step 1 to git's staging area via 'git add' and commit it locally.
5. Remove all the contents of the new docs and replace it with the contents of the
   main docs directory, updating any version-specific links (e.g. to a
   specific branch of the GitHub repository) to use the new version.
   rm -rf content/en/docs/v0.2.0; cp -R content/en/docs/main content/en/docs/v0.2.0
6. Update site/config.toml to include entries for the new version.
   • Add the version to the [params.versions.all] array
   • If the version is meant to be the latest version, change the params.latest_stable_version parameter as well.
7. Remove any deprecated/archived release documentation that is no longer supported
   rm -rf content/en/docs/v0.0.1
8. The unstaged changes in the working directory can now easily be diff'ed to review
   all docs changes made since the previous tagged version. Once the unstaged changes
   are ready, they can be added using 'git add' and then committed.

[elevran]

possible approach (verify still works correctly after each step):

• change all links to explicit file names, without using {{< ref/relref ... >}}
  • optionally, move all links to end of doc using named links
• move current docs under docs/main, fix links to docs and add frontmatter version (cascaded) set to the correct version in docs/vX.Y.Z/_index.md
• create a copy under docs/v0.1.0 (based on the tag) (ensure version is set in the _index.md)
• change the docs/_index.md to serve as collection only
• enable version selector, add version(s) to config.toml, set default version to "stable" (e.g. v0.1.0)
• enable use of stable/current_version to refer to the right locations from unversioned pages (e.g., landing and overview pages)
• document the process for cutting a new release (moved to issue Document/automate process for creating a new release version #531)
• add website redirects to docs URLs (/docs -> /docs/<stable>) (moved to issue [website] add URL redirects to docs? #532)