Changes to support documentation versioning (#528)

* Changes references in preparation for versioning 
    - use named references, bundled at the bottom of each page
* Move docs to docs/main
    - move all folders under `docs` directory to `docs/main`. This will allow addition of `docs/v0.1.0` etc afterwards
    - fix links to `docs` and sub-topics in landing page
* Added v0.1.0 documentation
    - based on v0.1.0 tag
* set frontmatter for main doc collection
* set toplevel docs as collection
* enabled version selector and versions
* make shortcodes and links version aware
    - modify shortcodes to accept @Version@ in parameters and replace with latest_stable_version
    - use `{{ site.Params.latest_stable_version }}` in HTML (e.g., shortcodes with known links)
    - use `{{< param latest_stable_version >}}` in markdown
* enable foldable sidebar links
* change in link syntax
    - replaced links to markdown files with {{< relref >}} (sidenote: no longer linkable in IDE or GH...)
    - replaced page section targets with section name (foo/_index.md => foo/).
       Using relref/ref to Section pages is not supported: https://discourse.gohugo.io/t/how-to-link-to-section-pages-with-ref-relref-shortcodes/5952/10
     - use of relative path is required for pages not in current directory (i.e., `{{< relref "foo/bar" >}}` => `{{< relref "../foo/bar" >}}`

---------

Signed-off-by: Etai Lev Ran <[email protected]>

website/config.toml

@@ -95,7 +95,7 @@ copyright = "The ClusterLink Authors"
 
 # Menu title if your navbar has a versions selector to access old versions of your site.
 # This menu appears only if you have at least one [params.versions] set.
-# version_menu = "Releases"
+version_menu = "Versions"
 
 # Flag used in the "version-banner" partial to decide whether to display a
 # banner on every page indicating that this is an archived version of the docs.
@@ -111,6 +111,8 @@ archived_version = false
 # point people to the main doc site.
 # url_latest_version = "https://clusterlink.net"
 
+latest_stable_version = "v0.1.0"
+
 # Repository configuration (URLs for in-page links to opening issues and suggesting changes)
 github_repo = "https://github.com/clusterlink-net/clusterlink"
 # An optional link to a related project repo. For example, the sibling repository where your product code lives.
@@ -143,9 +145,11 @@ navbar_logo = true
 # Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage.
 navbar_translucent_over_cover_disable = false
 # Enable to show the side bar menu in its compact state.
-sidebar_menu_compact = false
+sidebar_menu_compact = true
+# Enable foldable sidebar menu
+sidebar_menu_foldable = true
 # Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)
-sidebar_search_disable = false
+sidebar_search_disable = true
 
 # Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events.
 # This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set.
@@ -192,6 +196,20 @@ weight = 50
 url = "https://github.com/clusterlink-net/clusterlink/"
 pre = "<i class='fa-brands fa-github'></i>"
 
+[[menu.main]]
+name = "Docs"
+weight = 10
+url = "/docs/v0.1.0"
+pre = "<i class='fa-solid fa-book'></i>"
+
+# Add your release versions here
+[[params.versions]]
+version = "main-DRAFT"
+url = "/docs/main"
+
+[[params.versions]]
+version = "v0.1.0"
+url = "/docs/v0.1.0/"
 
 # hugo module configuration
 [module]

website/content/en/_index.md

@@ -3,7 +3,7 @@ title: ClusterLink
 ---
 
 {{< blocks/cover image_anchor="smart" height="auto" color="secondary" >}}
- {{% clusterlink/intro logo="clusterlink_logo.png" buttontext="Get Started" buttonlink="docs/getting-started" %}}Securely connecting<br />applications across multi-cloud{{% /clusterlink/intro %}}
+ {{% clusterlink/intro logo="clusterlink_logo.png" buttontext="Get Started" url="/docs/@VERSION@/getting-started" %}}Securely connecting<br />applications across multi-cloud{{% /clusterlink/intro %}}
  {{< blocks/link-down color="secondary" >}}
 
 {{< /blocks/cover >}}
@@ -27,11 +27,11 @@ title: ClusterLink
 {{< blocks/section color="primary" type="row" >}}
 <div width="100%" align="center" style="display: flex; background-image: url('backgrounds/section4.jpg'); background-size: 100%; <!--border-style: solid;-->">
 
-{{% clusterlink/card icon="icons/icon1.png" title="Overview" url="docs/overview" %}}Learn more about ClusterLink: what it is, how it works, and how it compares with existing solutions.{{% /clusterlink/card %}}
+{{% clusterlink/card icon="icons/icon1.png" title="Overview" url="/docs/@VERSION@/overview" %}}Learn more about ClusterLink: what it is, how it works, and how it compares with existing solutions.{{% /clusterlink/card %}}
 
-{{% clusterlink/card icon="icons/icon2.png" title="Tutorials" url="docs/tutorials" %}}Visit the tutorials for guided learning paths to try out ClusterLink. We'll walk you through the steps to access the functionality so that you can ace your first use case.{{% /clusterlink/card %}}
+{{% clusterlink/card icon="icons/icon2.png" title="Tutorials" url="/docs/@VERSION@/tutorials" %}}Visit the tutorials for guided learning paths to try out ClusterLink. We'll walk you through the steps to access the functionality so that you can ace your first use case.{{% /clusterlink/card %}}
 
-{{% clusterlink/card icon="icons/icon3.png" title="Concepts" url="docs/concepts"%}}Learn about the background and broader context behind ClusterLink. With an understanding of how it works and why, you can use it most effectively.{{% /clusterlink/card %}}
+{{% clusterlink/card icon="icons/icon3.png" title="Concepts" url="/docs/@VERSION@/concepts"%}}Learn about the background and broader context behind ClusterLink. With an understanding of how it works and why, you can use it most effectively.{{% /clusterlink/card %}}
 
 </div>
 {{< /blocks/section >}}

website/content/en/docs/_index.md

@@ -1,5 +1,7 @@
 ---
-title: Documentation
-linkTitle: Docs
-menu: {main: {weight: 10, pre: "<i class='fa-solid fa-book'></i>" }}
+title: Documentation Versions
+linkTitle: Versions
+simple_list: true
 ---
+
+Welcome to the ClusterLink docs! The following doc versions are available:

website/content/en/docs/main/_index.md

@@ -0,0 +1,12 @@
+---
+title: main (DRAFT)
+cascade:
+  version: main
+  versName: &name main (DRAFT)
+  git_version_tag: main
+  exclude_search: false
+linkTitle: *name
+simple_list: true
+weight: -9999 # Weight for doc version vX.Y should be -(100*X + Y)0
+# For example: v0.2.x => -20 v3.6.7 => -3060. `main` is arbitrarily set to -9999
+---

website/content/en/docs/concepts/fabric.md → website/content/en/docs/main/concepts/fabric.md

@@ -4,9 +4,9 @@ description: Defining a ClusterLink fabric
 weight: 10
 ---
 
-The concept of a *Fabric* encapsulates a set of cooperating [peers]({{< ref "peers" >}}).
- All peers in a fabric can communicate and may share [services]({{< ref "services" >}})
- between them, with access governed by [policies]({{< ref "policies" >}}).
+The concept of a *Fabric* encapsulates a set of cooperating [peers][concept-peer].
+ All peers in a fabric can communicate and may share [services][concept-service]
+ between them, with access governed by [policies][concept-policy].
  The Fabric acts as a root of trust for peer to peer communications (i.e.,
  it functions as the certificate authority enabling mutual authentication between
  peers).
@@ -43,6 +43,11 @@ This command will create the CA files `cert.pem` and `key.pem` in a directory na
 
 ## Related tasks
 
-Once a `Fabric` has been created and initialized, you can proceed with configuring
- [peers]({{< ref "peers" >}}). For a complete, end to end, use case please refer to the
- [iperf tutorial]({{< ref iperf >}}).
+Once a Fabric has been created and initialized, you can proceed with configuring
+ [peers][concept-peer]. For a complete, end to end, use case please refer to the
+ [iperf tutorial][tutorial-iperf].
+
+[concept-peer]: {{< relref "peers" >}}
+[concept-service]: {{< relref "services" >}}
+[concept-policy]: {{< relref "policies" >}}
+[tutorial-iperf]: {{< relref "../tutorials/iperf" >}}

website/content/en/docs/concepts/peers.md → website/content/en/docs/main/concepts/peers.md

@@ -5,11 +5,11 @@ weight: 20
 ---
 
 A *Peer* represents a location, such as a Kubernetes cluster, participating in a
- [fabric]({{< ref "fabric" >}}). Each peer may host one or more [services]({{< ref "services" >}})
+ [fabric][concept-fabric]. Each peer may host one or more [services][concept-service]
  it wishes to share with other peers. A peer is managed by a peer administrator,
  which is responsible for running the ClusterLink control and data planes. The
  administrator will typically deploy the ClusterLink components by configuring
- the [deployment CR]({{< ref "operator#deploy-cr-instance" >}}). They may also wish to provide
+ the [deployment CR][operator-cr]. They may also wish to provide
  (often) coarse-grained access policies in accordance with high level corporate
  policies (e.g., "production peers should only communicate with other production peers").
 
@@ -25,7 +25,7 @@ Once a peer has been added to a fabric, it can communicate with any other peer
 The following assume that you have access to the `clusterlink` CLI and one or more
  peers (i.e., clusters) where you'll deploy ClusterLink. The CLI can be downloaded
  from the ClusterLink [releases page on GitHub](https://github.com/clusterlink-net/clusterlink/releases/latest).
- It also assumes that you have access to the [previously created]({{< ref "fabric#create-a-new-fabric-ca" >}})
+ It also assumes that you have access to the [previously created][concept-fabric-new]
  fabric CA files.
 
 ## Initializing a new peer
@@ -89,8 +89,9 @@ This command will deploy the ClusterLink deployment CRDs using the current
  in order to install CRDs into the cluster.
  The ClusterLink operator is installed to the `clusterlink-operator` namespace.
  The CA, peer certificate, and private key are set as K8s secrets
- in the namespace where ClusterLink components are installed, which by default is `clusterlink-system`.
- You can confirm the successful completion of this step using the following commands:
+ in the namespace where ClusterLink components are installed, which by default is
+ `clusterlink-system`. You can confirm the successful completion of this step
+ using the following commands:
 
 ```sh
 kubectl get crds
@@ -129,7 +130,7 @@ After the operator is installed, you can deploy ClusterLink by applying
  Configurations affecting the entire peer, such as the list of known peers, are also maintained
  in the same namespace.
 
-Refer to the [getting started guide]({{< ref "users#setup" >}}) for a description
+Refer to the [operator documentation][operator-cli-flags] for a description
  of the ClusterLink CR fields.
 
 ## Add or remove peers
@@ -150,27 +151,26 @@ Managing peers is done by creating, deleting and updating peer CRs
 
 ```go
 type Peer struct {
-	metav1.TypeMeta   `json:",inline"`
-	metav1.ObjectMeta `json:"metadata,omitempty"`
+    metav1.TypeMeta   `json:",inline"`
+    metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec PeerSpec `json:"spec"`
-	Status PeerStatus `json:"status,omitempty"`
+    Spec PeerSpec `json:"spec"`
+    Status PeerStatus `json:"status,omitempty"`
 }
 
 
 type PeerSpec struct {
-	Gateways []Endpoint `json:"gateways"`
+    Gateways []Endpoint `json:"gateways"`
 }
 
 type PeerStatus struct {
-	Conditions []metav1.Condition `json:"conditions,omitempty"`
+    Conditions []metav1.Condition `json:"conditions,omitempty"`
 }
 
 type Endpoint struct {
-	Host string `json:"host"`
-	Port uint16 `json:"port"`
+    Host string `json:"host"`
+    Port uint16 `json:"port"`
 }
-
 ```
 
 {{% /expand %}}
@@ -179,13 +179,13 @@ There are two fundamental attributes in the peer CRD: the peer name and the list
  ClusterLink gateway endpoints through which the remote peer's services are available.
  Peer names are unique and must align with the Subject name present in their certificate
  during connection establishment. The name is used by importers in referencing an export
- (see [here]({{< ref "services" >}}) for details).
+ (see [here][concept-service] for details).
 
 Gateway endpoint would typically be a implemented via a `NodePort` or `LoadBalancer`
  K8s service. A `NodePort` service would typically be used in local deployments
  (e.g., when running in kind clusters during development) and a `LoadBalancer` service
  would be used in cloud based deployments. These can be automatically configured and
- created via the [ClusterLink CR]({{< ref "peers#deploy-clusterlink-via-the-operator-and-clusterlink-cr" >}}).
+ created via the [ClusterLink CR][concept-peer-deploy-via-cr].
  The peer's status section includes a `Reachable` condition indicating whether the peer is currently reachable,
  and in case it is not reachable, the last time it was.
 
@@ -197,5 +197,14 @@ Gateway endpoint would typically be a implemented via a `NodePort` or `LoadBalan
 
 Once a peer has been created and initialized with the ClusterLink control and data
  planes as well as one or more remote peers, you can proceed with configuring
- [services]({{< ref "services" >}}) and [policies]({{< ref "policies" >}}).
- For a complete end to end use case, refer to the [iperf toturial]({{< ref "iperf" >}}).
+ [services][concept-service] and [policies][concept-policy].
+ For a complete end to end use case, refer to the [iperf tutorial][tutorial-iperf].
+
+[concept-fabric]: {{< relref "fabric" >}}
+[concept-fabric-new]: {{< relref "fabric#create-a-new-fabric-ca" >}}
+[concept-service]: {{< relref "services" >}}
+[concept-policy]: {{< relref "policies" >}}
+[operator-cr]: {{< relref "../tasks/operator#deploy-cr-instance" >}}
+[operator-cli-flags]: {{< relref "../tasks/operator#commandline-flags" >}}
+[concept-peer-deploy-via-cr]: {{< relref "peers#deploy-clusterlink-via-the-operator-and-clusterlink-cr" >}}
+[tutorial-iperf]: {{< relref "../tutorials/iperf" >}}

website/content/en/docs/concepts/policies.md → website/content/en/docs/main/concepts/policies.md

@@ -14,7 +14,7 @@ Access policies allow users and administrators fine-grained control over
  as well as segmenting the fabric into trust zones.
 
 ClusterLink's access policies are based on attributes that are attached to
- [peers]({{< ref "peers" >}}), [services]({{< ref "services" >}}) and client workloads.
+ [peers][concept-peer], [services][concept-service] and client workloads.
  Each attribute is a key:value pair, similar to how
  [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
  are used in Kubernetes. This approach, called ABAC (Attribute Based Access Control),
@@ -59,7 +59,7 @@ For a connection to be established, both the ClusterLink gateway on the client
 ## Prerequisites
 
 The following assumes that you have `kubectl` access to two or more clusters where ClusterLink
- has already been [deployed and configured]({{% ref "users#setup" %}}).
+ has already been [deployed and configured][getting-started-user-setup].
 
 ### Creating access policies
 
@@ -146,3 +146,7 @@ spec:
 ```
 
 More examples are available [here](https://github.com/clusterlink-net/clusterlink/tree/main/pkg/policyengine/examples)
+
+[concept-peer]: {{< relref "peers" >}}
+[concept-service]: {{< relref "services" >}}
+[getting-started-user-setup]: {{< relref "../getting-started/users#setup" >}}

website/content/en/docs/concepts/services.md → website/content/en/docs/main/concepts/services.md

@@ -6,13 +6,13 @@ weight: 30
 
 ClusterLink uses services as the unit of sharing between peers.
  One or more peers can expose an (internal) K8s Service to
- be consumed by other [peers]({{% ref "peers" %}}) in the [fabric]({{% ref "fabric" %}}).
+ be consumed by other [peers][concept-peer] in the [fabric][concept-fabric].
  A service is exposed by creating an *Export* CR referencing it in the
  source cluster. Similarly, the exported service can be made accessible to workloads
  in a peer by defining an *Import* CR in the destination cluster[^KEP-1645].
  Thus, service sharing is an explicit operation. Services are not automatically
  shared by peers in the fabric. Note that the exporting cluster must be
- [configured as a peer]({{% ref "peers#add-or-remove-peers" %}}) of the importing
+ [configured as a peer][concept-peer-management] of the importing
  cluster.
 
 {{< notice info >}}
@@ -46,7 +46,7 @@ Orchestration of service sharing is the responsibility of users wishing to
 ## Prerequisites
 
 The following assume that you have `kubectl` access to two or more clusters where ClusterLink
- has already been [deployed and configured]({{% ref "users#setup" %}}).
+ has already been [deployed and configured][getting-started-user-setup].
 
 ### Exporting a service
 
@@ -93,10 +93,10 @@ The ExportSpec defines the following fields:
 
 Note that exporting a Service does not automatically make is accessible to other
  peers, but only enables *potential* access. To complete service sharing, you must
- define at least one [access control policy]({{% ref "policies" %}}) that allows
+ define at least one [access control policy][concept-policy] that allows
  access in the exporting cluster.
  In addition, users in consuming clusters must still explicitly configure
- [service imports](#importing-a-service) and [policies]({{% ref "policies" %}})
+ [service imports](#importing-a-service) and [policies][concept-policy]
  in their respective namespaces.
 
 {{% expand summary="Example YAML for `kubectl apply -f <export_file>`" %}}
@@ -188,7 +188,7 @@ The ImportSpec defines the following fields:
 
 As with exports, importing a service does not automatically make it accessible by
  workloads, but only enables *potential* access. To complete service sharing,
- you must define at least one [access control policy]({{% ref "policies" %}}) that
+ you must define at least one [access control policy][concept-policy] that
  allows access in the importing cluster. To grant access, a connection must be
  evaluated to "allow" by both egress (importing cluster) and ingress (exporting
  cluster) policies.
@@ -214,8 +214,8 @@ spec:
 ## Related tasks
 
 Once a service is exported and imported by one or more clusters, you should
- configure [polices]({{% ref "policies" %}}) governing its access.
- For a complete end to end use case, refer to [iperf toturial]({{< ref "iperf" >}}).
+ configure [polices][concept-policy] governing its access.
+ For a complete end to end use case, refer to [iperf tutorial][tutorial-iperf].
 
 [^KEP-1645]: While using similar terminology as the Kubernetes Multicluster Service
  enhancement proposal ([MCS KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/1645-multi-cluster-services-api)),
@@ -226,3 +226,10 @@ Once a service is exported and imported by one or more clusters, you should
  typically only a small subset in a multi-port service is meant to be user
  accessible, and other ports are service internal (e.g., ports used for internal
  service coordination and replication).
+
+[concept-fabric]: {{< relref "fabric" >}}
+[concept-peer]: {{< relref "peers" >}}
+[concept-peer-management]: {{< relref "peers#add-or-remove-peers" >}}
+[concept-policy]: {{< relref "policies" >}}
+[tutorial-iperf]: {{< relref "../tutorials/iperf" >}}
+[getting-started-user-setup]: {{< relref "../getting-started/users#setup" >}}

website/content/en/docs/doc-contribution/_index.md → website/content/en/docs/main/doc-contribution/_index.md

@@ -58,7 +58,7 @@ If you want to run your own local Hugo server to preview your changes as you wor
 
 <!-- TODO should add a dedicated getting-started for website authoring -->
 
-1. Follow the instructions in [Getting started]({{< ref "getting-started" >}}) to install Hugo
+1. Follow the instructions in [Getting started][getting-started-documentation] to install Hugo
  and any other tools you need. You'll need at least **Hugo version 0.110** (we recommend
  using the most recent available version), and it must be the **extended** version,
  which supports SCSS.
@@ -82,3 +82,6 @@ If you've found a problem in the docs, but you're not sure how to fix it yoursel
 * [Hugo documentation](https://gohugo.io/documentation/): Comprehensive reference for Hugo.
 * [Github Hello World!](https://guides.github.com/activities/hello-world/): A basic
  introduction to GitHub concepts and workflow.
+
+[getting-started-documentation]: ../getting-started/
+<!-- a documentation specific getting started guide is missing. Tracked in issue #526 -->

website/content/en/docs/main/getting-started/_index.md

@@ -0,0 +1,15 @@
+---
+title: Getting Started
+description: Getting started guides for users and developers
+weight: 20
+---
+
+The following provide quick start guides for [users][user-getting-started] and
+ [developers][dev-getting-started].
+
+If you're a content author, wishing to contribute additional documentation or guides,
+ please refer to the [contribution guidelines][doc-contribution].
+
+[user-getting-started]: {{< relref "users" >}}
+[dev-getting-started]: {{< relref "developers" >}}
+[doc-contribution]: ../doc-contribution/