feat: implement documentation versioning and update header for versio… (#487)

<!-- markdownlint-disable MD041 -->
#### What this PR does / why we need it
The PR introduces a version toggle on the website. It is using a
versions.json in the data/ folder that contains all available versions.
New versions of the website need to be cut off from the main branch and
afterwards built using the baseURL + the new version and merge this into
the public/ folder. This holds all versions in parallel, accessible by
introducing a v2 in the URL, since Gh pages are not able to use multiple
branches.

```
hugo build  --baseURL https://ocm.software/v2/ \
     --destination ./public/v2 \
     --minify --gc
```

The PR will introduce the version toggle and the version "current" which
will live on the root level in the public/ folder that will be
published.

Related to
open-component-model/ocm-project#482

Signed-off-by: Gerald Morrison (SAP) <[email protected]>
Co-authored-by: Gerald Morrison (SAP) <[email protected]>

Author: morri-son

config/_default/hugo.toml

@@ -87,9 +87,7 @@ lastMod = false
   tag = "tags"
 
 [permalinks]
-  blog = "/blog/:slug/"
-  docs = "/docs/:sections[1:]/:slug/"
-# docs = "/docs/1.0/:sections[1:]/:slug/"
+  docs = "/docs/:sections[1:]/:title/"
 
 [minify.tdewolff.html]
   keepWhitespace = false

config/_default/module.toml

@@ -86,3 +86,13 @@
 [[mounts]]
   source = "static"
   target = "static"
+
+## Reference Docs mounted from other repositories
+## Use @main to always use the latest version of the repository.
+## Use version tags to pin to a specific version.
+
+#[[imports]]
+#  path = "github.com/open-component-model/open-component-model@main"
+#  [[imports.mounts]]
+#    source = "docs/reference/cli"
+#    target = "content/docs/reference/ocm-cli"

config/_default/params.toml

@@ -51,8 +51,16 @@ mainSections = ["docs"]
   showMissingLanguages = true # whether or not to show untranslated languages in the language menu; true (default) or false
 
   # Versioning
-  docsVersioning = false # false (default) or true
-  docsVersion = "1.0"
+  # Offers toggle to maintain multiple versions of the same documentation
+  # Parameters are used in the layouts/partials/header/header.html template
+  #
+  # Central versions.json containinig all parallel versions lies in data/ folder 
+  # and NEEDS to be maintained in the main branch BEFORE a new version branch is cut off to 
+  # be available in the version switcher of all versions.
+
+  docsVersioning = true 
+  docsVersion = "current"
+  defaultVersion = "current"
 
   # UX
   headerBar = true # true (default) or false

data/docs-versions.yml

@@ -0,0 +1,4 @@
+{
+  "defaultVersion": "current",
+  "versions": [ "current" ]
+}

data/versions.json

@@ -147,7 +147,7 @@ <h5 class="offcanvas-title fw-bold" id="offcanvasNavMainLabel">{{ .Site.Params.T
         {{ partial "main/showFlexSearch" . }}
         {{ $showFlexSearch := .Scratch.Get "showFlexSearch" -}}
         {{ if $showFlexSearch -}}
-        <button type="button" id="searchToggleDesktop" class="btn btn-link nav-link p-2 d-none d-lg-block" aria-label="Search website">
+        <button type="button" id="searchToggleDesktop" class="btn btn-link nav-link p-2 d-none d-lg-block order-lg-3" aria-label="Search website">
           <svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-search" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
             <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
             <circle cx="10" cy="10" r="7"></circle>
@@ -207,33 +207,57 @@ <h5 class="offcanvas-title fw-bold" id="offcanvasNavMainLabel">{{ .Site.Params.T
         </div>
         {{ end -}}
 
-        <!-- Versioning dropdown  -->
-        {{ if eq site.Params.doks.docsVersioning true -}}
+        <!-- Versioning dropdown -->
+        {{ if site.Params.doks.docsVersioning }}
+        {{/* load versions.json from data/ */}}
+        {{ $versionsData := site.Data.versions }}
 
-        <div class="dropdown mt-1 order-lg-3">
-          <button class="btn btn-dropdown dropdown-toggle" id="doks-versions" data-bs-toggle="dropdown" aria-expanded="false" data-bs-display="static" aria-label="Toggle version menu">
-            <span class="d-none">Doks</span> v{{ site.Params.doks.docsVersion }}
+        {{ if $versionsData.versions }}
+        {{ $currentVer := site.Params.doks.docsVersion }}
+
+        <div class="dropdown mt-1 order-lg-1">
+          <button class="btn btn-dropdown dropdown-toggle"
+                  id="doks-versions"
+                  data-bs-toggle="dropdown"
+                  aria-expanded="false"
+                  data-bs-display="static"
+                  aria-label="Toggle version menu">
+            Versions
             <span class="dropdown-caret">
-              <svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-chevron-down" width="24" height="24" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
-                <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
-                <path d="M6 9l6 6l6 -6"></path>
+              <svg xmlns="http://www.w3.org/2000/svg"
+                  class="icon icon-tabler icon-tabler-chevron-down"
+                  width="24" height="24" viewBox="0 0 24 24" stroke-width="1.5"
+                  stroke="currentColor" fill="none"
+                  stroke-linecap="round" stroke-linejoin="round">
+                <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
+                <path d="M6 9l6 6l6 -6"/>
               </svg>
             </span>
           </button>
-          <ul class="dropdown-menu dropdown-menu-lg-end me-lg-2 shadow rounded border-0" aria-labelledby="doks-versions">
-            <li><a class="dropdown-item current" aria-current="true" href="/docs/{{ site.Params.doks.docsVersion }}/prologue/introduction/">Latest ({{ site.Params.doks.docsVersion }}.x)</a></li>
-            <li><hr class="dropdown-divider"></li>
-            <li><a class="dropdown-item" href="/docs/0.2/prologue/introduction/">v0.2.x</a></li>
-            <li><a class="dropdown-item" href="/docs/0.1/prologue/introduction/">v0.1.x</a></li>
-            <li><hr class="dropdown-divider"></li>
-            <li><a class="dropdown-item" href="/docs/versions/">All versions</a></li>
+          
+          <ul class="dropdown-menu dropdown-menu-lg-end me-lg-2 shadow rounded border-0"
+              aria-labelledby="doks-versions">
+            {{ range $versionsData.versions }}
+              {{ $isDefault := eq . $versionsData.defaultVersion }}
+              {{ $isCurrent := eq . $currentVer }}
+              {{ $versionPath := cond $isDefault "/" (printf "/%s/" .) }}
+              
+              <li>
+                <a class="dropdown-item{{ if $isCurrent }} current{{ end }}"
+                  {{ if $isCurrent }}aria-current="true"{{ end }}
+                  href="{{ $versionPath }}docs/overview/about">
+                  {{ . }}{{ if $isDefault }} (latest){{ end }}
+                </a>
+              </li>
+            {{ end }}
           </ul>
         </div>
-        {{ end -}}
+        {{ end }}
+        {{ end }}
 
         <!-- Color mode toggler -->
         {{ if .Site.Params.doks.colorModeToggler }}
-          <button id="buttonColorMode" class="btn btn-link mx-auto nav-link p-0 ms-lg-2 me-lg-1" type="button" aria-label="Toggle theme">
+          <button id="buttonColorMode" class="btn btn-link mx-auto nav-link p-0 ms-lg-2 me-lg-1 order-lg-4" type="button" aria-label="Toggle theme">
             <svg data-bs-theme-value="dark" xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-moon" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
               <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
               <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path>
@@ -278,5 +302,5 @@ <h5 class="offcanvas-title fw-bold" id="offcanvasNavMainLabel">{{ .Site.Params.T
 
 <!-- Search modal -->
 {{ if site.Params.doks.flexSearch -}}
-{{ partial "header/search-modal" . }}
-{{ end -}}
+  {{ partial "header/search-modal" . }}
+{{ end -}}