Merge pull request #478 from h-enk/versioning

feat: add versioning setup

assets/js/index.js

@@ -102,7 +102,7 @@ Source:
     {{ range $index, $element := $list -}}
       {
         id: {{ $index }},
-        href: "{{ .Permalink }}",
+        href: "{{ .RelPermalink }}",
         title: {{ .Title | jsonify }},
         description: {{ .Params.description | jsonify }},
         content: {{ .Content | jsonify }}

config/_default/config.toml

@@ -62,6 +62,7 @@ rel  = "sitemap"
 
 [permalinks]
   blog = "/blog/:title/"
+# docs = "/docs/1.0/:sections[1:]/:title/"
 
 [minify.tdewolff.html]
   keepWhitespace = false

config/_default/menus/menus.en.toml

@@ -13,6 +13,7 @@
 [[main]]
   name = "Docs"
   url = "/docs/prologue/introduction/"
+# url = "/docs/1.0/prologue/introduction/"
   weight = 10
 
 [[main]]

config/_default/params.toml

@@ -6,6 +6,9 @@ titleSeparator = "-"
 titleAddition = "Modern Documentation Theme"
 description = "Doks is a Hugo theme helping you build modern documentation websites that are secure, fast, and SEO-ready — by default."
 
+## Documentation
+# docsVersion = "1.0"
+
 ## Open Graph
 images = ["doks.png"]
 ogLocale = "en_US"
@@ -79,4 +82,4 @@ editPage = false
   kaTex = false
   collapsibleSidebar = true
   multilingualMode = false
-  docsVersioning = false # Not yet functional
+  docsVersioning = false

content/en/versions.md

@@ -0,0 +1,11 @@
+---
+title: "Versions"
+description: ""
+lead: "An appendix of hosted documentation for nearly every release of Doks, from v0 through v3."
+date: 2021-09-24T08:50:23+02:00
+lastmod: 2021-09-24T08:50:23+02:00
+draft: true
+images: []
+layout: versions
+url: "/docs/versions/"
+---

data/docs-versions.yml

@@ -0,0 +1,60 @@
+# - group: v1.x
+#   baseurl: "https://getbootstrap.com"
+#   description: "Every minor and patch release from v1 is listed below."
+#   versions:
+#     - v: "1.0.0"
+#     - v: "1.1.0"
+#     - v: "1.1.1"
+#     - v: "1.2.0"
+#     - v: "1.3.0"
+#     - v: "1.4.0"
+#
+# - group: v2.x
+#   baseurl: "https://getbootstrap.com"
+#   description: "Every minor and patch release from v2 is listed below."
+#   versions:
+#     - v: "2.0.0"
+#     - v: "2.0.1"
+#     - v: "2.0.2"
+#     - v: "2.0.3"
+#     - v: "2.0.4"
+#     - v: "2.1.0"
+#     - v: "2.1.1"
+#     - v: "2.2.0"
+#     - v: "2.2.1"
+#     - v: "2.2.2"
+#     - v: "2.3.0"
+#     - v: "2.3.1"
+#     - v: "2.3.2"
+#
+# - group: v3.x
+#   baseurl: "https://getbootstrap.com/docs"
+#   description: "Every minor and patch release from v3 is listed below. Last update was v3.4.1."
+#   versions:
+#     - v: "3.3"
+#     - v: "3.4"
+#
+# - group: v4.x
+#   baseurl: "https://getbootstrap.com/docs"
+#   description: "Our previous major release with its minor releases. Last update was v4.6.0."
+#   versions:
+#     - v: "4.0"
+#     - v: "4.1"
+#     - v: "4.2"
+#     - v: "4.3"
+#     - v: "4.4"
+#     - v: "4.5"
+#     - v: "4.6"
+
+- group: v0.x
+  baseurl: "/docs"
+  description: "Current major release. Last update was v0.2.0."
+  versions:
+    - v: "0.1"
+    - v: "0.2"
+
+- group: v1.x
+  baseurl: "/docs"
+  description: "Every minor and patch release from v1 is listed below. Last update was v1.0.0."
+  versions:
+    - v: "1.0"

layouts/_default/versions.html

@@ -0,0 +1,27 @@
+{{ define "main" }}
+  <article>
+    <h1>{{ .Title }}</h1>
+    <p class="lead">{{ .Params.lead | safeHTML }}</p>
+    {{ .Content }}
+    <div class="row">
+      {{ range $release := sort (index $.Site.Data "docs-versions") "group" "desc" -}}
+      <div class="col-md-8 col-lg-4 col-xl mb-4">
+        <h2>{{ $release.group }}</h2>
+        <p>{{ $release.description }}</p>
+        {{ $versions := sort $release.versions "v" "desc" -}}
+        {{ range $i, $version := $versions -}}
+          {{ $len := len $versions -}}
+          {{ if (eq $i 0) }}<div class="list-group">{{ end }}
+            <a class="list-group-item list-group-item-action py-2 text-primary{{ if (eq $version.v $.Site.Params.docsVersion) }} d-flex justify-content-between align-items-center{{ end }}" href="{{ $release.baseurl }}/{{ $version.v }}/">
+              {{ $version.v }}
+              {{ if (eq $version.v $.Site.Params.docsVersion) -}}
+              <span class="badge bg-primary">Latest</span>
+              {{ end -}}
+            </a>
+          {{ if (eq (add $i 1) $len) }}</div>{{ end }}
+        {{ end -}}
+      </div>
+      {{ end -}}
+    </div>
+  </article>
+{{ end }}

layouts/index.headers

@@ -2,8 +2,9 @@
   Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
   X-Content-Type-Options: nosniff
   X-XSS-Protection: 1; mode=block
-  Content-Security-Policy: default-src 'self'; frame-ancestors https://jamstackthemes.dev; manifest-src 'self'; connect-src 'self'; font-src 'self'; img-src 'self' data:; script-src 'self' 'sha512-RBYr6Ld4w1yVqaACrgrBLQfPgGhj/1jyacA74WxJ1KM6KVcSWymwrdDwb3HDcdpwiNJ5yssot1He0U9vXoQVlg=='; style-src 'self' 'unsafe-inline'
+  Content-Security-Policy: default-src 'self'; frame-ancestors https://jamstackthemes.dev; manifest-src 'self' https://*.netlify.app; connect-src 'self' https://*.netlify.app; font-src 'self' https://*.netlify.app; img-src 'self' https://*.netlify.app data:; script-src 'self' https://*.netlify.app 'sha512-RBYr6Ld4w1yVqaACrgrBLQfPgGhj/1jyacA74WxJ1KM6KVcSWymwrdDwb3HDcdpwiNJ5yssot1He0U9vXoQVlg=='; style-src 'self' https://*.netlify.app 'unsafe-inline'
   X-Frame-Options: SAMEORIGIN
   Referrer-Policy: strict-origin
   Feature-Policy: geolocation 'self'
-  Cache-Control: public, max-age=31536000
+  Cache-Control: public, max-age=31536000
+  Access-Control-Allow-Origin: *

layouts/index.html

@@ -6,8 +6,8 @@
     </div>
     <div class="col-lg-9 col-xl-8 text-center">
       <p class="lead">{{ .Params.lead | safeHTML }}</p>
-      <a class="btn btn-primary btn-lg px-4 mb-2" href="{{ "docs/prologue/introduction/" | relLangURL }}" role="button">{{ i18n "get-started" }}</a>
+      <a class="btn btn-primary btn-lg px-4 mb-2" href="/docs/{{ if .Site.Params.options.docsVersioning }}{{ .Site.Params.docsVersion }}/{{ end }}prologue/introduction/" role="button">Get Started</a>
-      <p class="meta">Open-source MIT Licensed. <a href="https://github.com/h-enk/doks">GitHub v{{ $data := getJSON "https://raw.githubusercontent.com/h-enk/doks/master/package.json" }}{{ $data.version }}</a></p>
+      <p class="meta">Open-source MIT Licensed. <a href="https://github.com/h-enk/doks-versioning-poc">GitHub v{{ $data := getJSON "/package.json" }}{{ $data.version }}</a></p>
     </div>
   </div>
 </section>

layouts/index.redirects

@@ -1,6 +1,13 @@
-# redirects for Netlify - https://www.netlify.com/docs/redirects/
 {{- range $p := .Site.Pages -}}
 {{- range .Aliases }}
 {{ . }} {{ $p.RelPermalink -}}
 {{- end }}
-{{- end -}}
+{{- end -}}
+
+# /docs/1.0/prologue/   /docs/1.0/prologue/introduction/
+# /docs/1.0/help/       /docs/1.0/help/how-to-update/
+# /docs/1.0/            /docs/1.0/prologue/introduction/
+# /docs/                /docs/1.0/prologue/introduction/
+#
+# /docs/0.1/*           https://v0-1-0--doks-versioning-poc.netlify.app/docs/0.1/:splat  200
+# /docs/0.2/*           https://v0-2-0--doks-versioning-poc.netlify.app/docs/0.2/:splat  200

layouts/partials/footer/script-footer.html

@@ -100,6 +100,6 @@
     <script src="{{ $mermaid.RelPermalink }}" integrity="{{ $mermaid.Data.Integrity }}" crossorigin="anonymous" defer></script>
   {{ end -}}
   {{ if and (.Site.Params.options.flexSearch) (eq .Section "docs") -}}
-    <script src="{{ $index.RelPermalink }}" integrity="{{ $index.Data.Integrity }}" crossorigin="anonymous" defer></script>
+    <script src="{{ $index.Permalink }}" integrity="{{ $index.Data.Integrity }}" crossorigin="anonymous" defer></script>
   {{ end -}}
 {{ end -}}

layouts/partials/head/stylesheet.html

@@ -6,6 +6,6 @@
   {{ $options := (dict "targetPath" "main.css" "outputStyle" "compressed" "includePaths" (slice "node_modules")) -}}
   {{ $css := resources.Get "scss/app.scss" | toCSS $options | postCSS (dict "config" "config/postcss.config.js") -}}
   {{ $secureCSS := $css | resources.Fingerprint "sha512" -}}
-  <link rel="stylesheet" href="{{ $secureCSS.Permalink | relURL }}" integrity="{{ $secureCSS.Data.Integrity }}" crossorigin="anonymous">
+  <link rel="stylesheet" href="{{ $secureCSS.Permalink }}" integrity="{{ $secureCSS.Data.Integrity }}" crossorigin="anonymous">
 {{ end -}}
 <noscript><style>img.lazyload { display: none; }</style></noscript>

layouts/partials/header/header.html

@@ -107,14 +107,13 @@
     {{ if eq .Site.Params.options.docsVersioning true -}}
     <div class="dropdown ms-3">
       <button class="btn btn-doks-light 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 d-lg-inline">Doks</span> v5.0
+        <span class="d-none d-lg-inline">Doks</span> v{{ .Site.Params.docsVersion }}
       </button>
-      <ul class="dropdown-menu dropdown-menu-end" aria-labelledby="doks-versions">
+      <ul class="dropdown-menu dropdown-menu-end shadow rounded border-0" aria-labelledby="doks-versions">
-        <li><a class="dropdown-item current" aria-current="true" href="/docs/5.0/">Latest (5.0.x)</a></li>
+        <li><a class="dropdown-item current" aria-current="true" href="/docs/{{ .Site.Params.docsVersion }}/prologue/introduction/">Latest ({{ .Site.Params.docsVersion }}.x)</a></li>
         <li><hr class="dropdown-divider"></li>
-        <li><a class="dropdown-item" href="https://getbootstrap.com/docs/4.6/">v4.6.x</a></li>
+        <li><a class="dropdown-item" href="/docs/0.2/prologue/introduction/">v0.2.x</a></li>
-        <li><a class="dropdown-item" href="https://getbootstrap.com/docs/3.4/">v3.4.1</a></li>
+        <li><a class="dropdown-item" href="/docs/0.1/prologue/introduction/">v0.1.x</a></li>
-        <li><a class="dropdown-item" href="https://getbootstrap.com/2.3.2/">v2.3.2</a></li>
         <li><hr class="dropdown-divider"></li>
         <li><a class="dropdown-item" href="/docs/versions/">All versions</a></li>
       </ul>