Refactor docs versions to major.minor variants (#477)

## Summary

Refactors the docs versioning structure from `v0`/`v1` to
per-minor-version directories (`v0`, `v1.0`, `v1.1`, `v1.2`), making the
site compatible with the push-based docs update pipeline from
cozystack/cozystack#2214.

### What changed

**Docs structure:**
- Renamed `content/en/docs/v1/` → `v1.0/`
- Bootstrapped `v1.1` and `v1.2` from `v1.0`, then pulled actual content
from `release-1.1` and `release-1.2` branches
- Added 301 redirect `/docs/v1/*` → `/docs/v1.0/:splat` in
`netlify.toml` for backward compatibility

**Version-aware Makefile:**
- `RELEASE_TAG=v1.2.1` automatically derives `DOC_VERSION=v1.2`,
`BRANCH=release-1.2`
- `override BRANCH` fixes the mismatch where cozystack passes
`BRANCH=release-1.2.1` but the actual branch is `release-1.2`
- New targets: `init-version` (bootstrap new version dir),
`download-openapi`, `download-openapi-all`

**OpenAPI spec out of git:**
- `v0` and `v1.0` keep `api.json` in-repo (no release asset available
for those versions)
- `v1.1` also keeps a copy in-repo (v1.1.x releases predate the
openapi.json artifact)
- `v1.2+` downloads `openapi.json` from GitHub releases at Netlify build
time via `hack/download_openapi.sh`
- `static/docs/*/cozystack-api/` added to `.gitignore`

**Version switcher UI:**
- Refactored from inline buttons to a Bootstrap dropdown — scales
cleanly as versions grow
- Fixed `version-banner.html` — replaced `int()` cast (breaks on `v1.0`)
with index-based comparison

**GitHub workflow:**
- `update-managed-apps.yaml` now accepts `RELEASE_TAG` via dispatch
payload or workflow input
- Daily sync targets latest version (read from `hugo.yaml`)
- Per-version PR branches: `update-managed-apps-v1.2`

### New scripts

- `hack/init_version.sh` — copies content from previous version, updates
all internal refs, removes `api.json`
- `hack/download_openapi.sh` — downloads openapi.json from GitHub
releases at build time (works without `gh` CLI)

### Note for cozystack/cozystack#2214

The `update-website-docs` job passes `BRANCH=release-X.Y.Z` (full
version) but cozystack release branches are `release-X.Y` (major.minor).
This PR handles the mismatch via `override BRANCH` in the Makefile, but
ideally the cozystack workflow should also be fixed to pass
`BRANCH=release-X.Y`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: myasnikovdaniil

.github/workflows/update-managed-apps.yaml

@@ -2,6 +2,10 @@ name: Sync documentation sources
 
 on:
   workflow_dispatch:
+    inputs:
+      release_tag:
+        description: 'Release tag (e.g., v1.2.1) — leave empty for latest version'
+        required: false
   # 03:00 UTC, 05:00 Prague, usually all PRs in cozystack/cozystack get merged before this time.
   schedule:
     - cron: '0 3 * * *'
@@ -10,7 +14,7 @@ on:
   # curl -XPOST -H "Authorization: token <PAT>" \
   #   -H "Accept: application/vnd.github.v3+json" \
   #   https://api.github.com/repos/cozystack/website/dispatches \
-  #   -d '{"event_type":"update_managed_apps"}'
+  #   -d '{"event_type":"update_managed_apps","client_payload":{"release_tag":"v1.2.1"}}'
   repository_dispatch:
     types: [update_managed_apps]
 
@@ -25,42 +29,87 @@ jobs:
         with:
           ref: 'main'
 
+      - name: Determine version parameters
+        id: version
+        env:
+          RELEASE_TAG_INPUT: ${{ github.event.client_payload.release_tag || github.event.inputs.release_tag || '' }}
+        run: |
+          # Validate release tag format if provided
+          if [[ -n "$RELEASE_TAG_INPUT" && ! "$RELEASE_TAG_INPUT" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Invalid release tag format: '$RELEASE_TAG_INPUT' (expected vX.Y.Z)"
+            exit 1
+          fi
+          RELEASE_TAG="$RELEASE_TAG_INPUT"
+
+          if [[ -n "$RELEASE_TAG" ]]; then
+            echo "release_tag=${RELEASE_TAG}" >> $GITHUB_OUTPUT
+            # Derive doc version for branch naming
+            VER="${RELEASE_TAG#v}"
+            MAJOR="${VER%%.*}"
+            MINOR="${VER#*.}"
+            MINOR="${MINOR%%.*}"
+            if [[ "$MAJOR" == "0" ]]; then
+              DOC_VERSION="v0"
+            else
+              DOC_VERSION="v${MAJOR}.${MINOR}"
+            fi
+            echo "doc_version=${DOC_VERSION}" >> $GITHUB_OUTPUT
+            echo "branch_suffix=${DOC_VERSION}" >> $GITHUB_OUTPUT
+          else
+            # Daily sync: target latest version from hugo.yaml
+            LATEST=$(grep 'latest_version_id' hugo.yaml | head -1 | awk '{print $2}' | tr -d '"')
+            echo "doc_version=${LATEST}" >> $GITHUB_OUTPUT
+            echo "branch_suffix=${LATEST}" >> $GITHUB_OUTPUT
+          fi
+
       - name: Update docs via script
+        env:
+          RELEASE_TAG: ${{ steps.version.outputs.release_tag }}
+          DOC_VERSION: ${{ steps.version.outputs.doc_version }}
         run: |
-          make update-all
+          if [[ -n "$RELEASE_TAG" ]]; then
+            make update-all RELEASE_TAG="$RELEASE_TAG"
+          else
+            make update-all DOC_VERSION="$DOC_VERSION"
+          fi
           git status -s
 
       # Commit and push any changes
       - name: Commit & push changes
+        env:
+          DOC_VERSION: ${{ steps.version.outputs.doc_version }}
         run: |
+          BRANCH="update-managed-apps-${DOC_VERSION}"
+
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git add content
           if git diff --cached --quiet; then
             echo "No changes to commit"
             exit 0
           fi
-          git branch -D update-managed-apps-reference || true
-          git checkout -b update-managed-apps-reference
-          git commit --signoff -m "[docs] Update managed apps reference $(date -u +'%Y-%m-%d %H:%M:%S')"
-          git push --force --set-upstream origin update-managed-apps-reference
+          git branch -D "$BRANCH" || true
+          git checkout -b "$BRANCH"
+          git commit --signoff -m "[docs] Update managed apps reference for ${DOC_VERSION} $(date -u +'%Y-%m-%d %H:%M:%S')"
+          git push --force --set-upstream origin "$BRANCH"
 
       - name: Open pull request if not exists
         env:
-          # gh CLI will pick this up for authentication
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOC_VERSION: ${{ steps.version.outputs.doc_version }}
         run: |
-          # Determine PR state; value will be OPEN if there's a fresh PR or MERGED otherwise.
-          # This workflow is reusing the same branch name, so it's not possible that the PR won't exist at all.
-          pr_state=$(gh pr view update-managed-apps-reference --json state --jq .state 2>/dev/null || echo "")
+          BRANCH="update-managed-apps-${DOC_VERSION}"
+
+          # Determine PR state
+          pr_state=$(gh pr view "$BRANCH" --json state --jq .state 2>/dev/null || echo "")
           echo "Current PR state: ${pr_state:-NONE}"
 
           if [[ "$pr_state" == "OPEN" ]]; then
             echo "An open pull request already exists – skipping creation."
           else
             gh pr create \
-              --title "[docs] Update managed apps reference" \
+              --title "[docs] Update managed apps reference for ${DOC_VERSION}" \
               --body "Automated update via workflow." \
-              --head update-managed-apps-reference \
+              --head "$BRANCH" \
               --base main
           fi

.gitignore

@@ -22,5 +22,8 @@ hugo/
 # IDE files
 .idea
 
+# Downloaded OpenAPI specs (fetched at build time)
+static/docs/*/cozystack-api/
+
 # Claude Code local settings
 .claude/

Makefile

@@ -1,17 +1,33 @@
-# Defaults (override on the command line: `make update-apps APPS="tenant redis" DEST_DIR="..."`)
+# Version derivation from RELEASE_TAG (e.g., v1.2.1 → DOC_VERSION=v1.2, BRANCH=v1.2.1)
+# When RELEASE_TAG is set, BRANCH is pinned to the exact tag for reproducible builds.
+RELEASE_TAG ?=
+ifdef RELEASE_TAG
+  _ver := $(patsubst v%,%,$(RELEASE_TAG))
+  _major := $(word 1,$(subst ., ,$(_ver)))
+  _minor := $(word 2,$(subst ., ,$(_ver)))
+  DOC_VERSION := $(if $(filter 0,$(_major)),v0,v$(_major).$(_minor))
+  override BRANCH := $(RELEASE_TAG)
+else
+  DOC_VERSION ?= v1.2
+  BRANCH ?= main
+endif
+
+# App lists (override on the command line: `make update-apps APPS="tenant redis"`)
 APPS       ?= tenant clickhouse foundationdb harbor redis mongodb openbao rabbitmq postgres nats kafka mariadb qdrant
 K8S       ?= kubernetes
 VMS       ?= vm-disk vm-instance
 NETWORKING       ?= vpc vpn http-cache tcp-balancer
 SERVICES       ?= bootbox etcd ingress monitoring seaweedfs
-APPS_DEST_DIR   ?= content/en/docs/v1/applications
-K8S_DEST_DIR   ?= content/en/docs/v1
-VMS_DEST_DIR   ?= content/en/docs/v1/virtualization
-NETWORKING_DEST_DIR   ?= content/en/docs/v1/networking
-SERVICES_DEST_DIR   ?= content/en/docs/v1/operations/services
-BRANCH     ?= main
-
-.PHONY: update-apps update-vms update-networking update-k8s update-services update-oss-health update-all template-apps template-vms template-networking template-k8s template-services template-all
+APPS_DEST_DIR   ?= content/en/docs/$(DOC_VERSION)/applications
+K8S_DEST_DIR   ?= content/en/docs/$(DOC_VERSION)
+VMS_DEST_DIR   ?= content/en/docs/$(DOC_VERSION)/virtualization
+NETWORKING_DEST_DIR   ?= content/en/docs/$(DOC_VERSION)/networking
+SERVICES_DEST_DIR   ?= content/en/docs/$(DOC_VERSION)/operations/services
+
+.PHONY: update-apps update-vms update-networking update-k8s update-services update-oss-health update-all \
+        template-apps template-vms template-networking template-k8s template-services template-all \
+        init-version download-openapi download-openapi-all serve
+
 update-apps:
 	./hack/update_apps.sh --apps "$(APPS)" --dest "$(APPS_DEST_DIR)" --branch "$(BRANCH)"
 
@@ -30,13 +46,29 @@ update-services:
 update-oss-health:
 	./hack/update_oss_health.py
 
-# requires cluster authentication
-# to be replaced with downloading a build/release artifact from github.com/cozystack/cozystack
-update-api:
-	kubectl get --raw '/openapi/v3/apis/apps.cozystack.io/v1alpha1' > content/en/docs/cozystack-api/api.json
+# Download openapi.json for a specific version from GitHub release
+download-openapi:
+ifndef RELEASE_TAG
+	$(error RELEASE_TAG is required for download-openapi (e.g., make download-openapi RELEASE_TAG=v1.2.1))
+endif
+	@mkdir -p static/docs/$(DOC_VERSION)/cozystack-api
+	@echo "Downloading openapi.json for $(RELEASE_TAG)..."
+	@curl -fsSL -o static/docs/$(DOC_VERSION)/cozystack-api/api.json \
+	  "https://github.com/cozystack/cozystack/releases/download/$(RELEASE_TAG)/openapi.json" \
+	  && echo "✓ Downloaded openapi.json for $(DOC_VERSION)" \
+	  || echo "⚠️  openapi.json not available for $(RELEASE_TAG)"
+
+# Download openapi.json for all versions at build time
+download-openapi-all:
+	./hack/download_openapi.sh
+
+# Initialize a new version directory from the previous version
+init-version:
+	./hack/init_version.sh --version "$(DOC_VERSION)"
 
-# doesn't include update-api, because it can't run in CI yet
+# doesn't include download-openapi (handled separately at build time)
 update-all:
+	$(MAKE) init-version
 	$(MAKE) update-apps
 	$(MAKE) update-vms
 	$(MAKE) update-networking

assets/scss/blocks/_nav.scss

@@ -248,36 +248,45 @@ nav.navbar {
   }
 }
 
-// Sidebar version switcher
+// Sidebar version switcher (dropdown)
 .version-switcher {
-  display: flex;
-  gap: 0.5rem;
   padding: 0.75rem 1rem;
 
-  &__item {
-    flex: 1;
-    text-align: center;
-    padding: 0.35rem 0.75rem;
+  &__toggle {
+    width: 100%;
+    padding: 0.4rem 0.75rem;
     border-radius: 0.25rem;
     font-size: 0.85rem;
     font-weight: 600;
     color: $cozy-dark-blue;
     background: rgba($cozy-dark-blue, 0.05);
     border: 1px solid rgba($cozy-dark-blue, 0.2);
-    text-decoration: none;
-    transition: background 0.15s, color 0.15s;
+    text-align: left;
+    cursor: pointer;
+    transition: background 0.15s;
 
     &:hover {
       background: rgba($cozy-dark-blue, 0.12);
     }
 
-    &--active {
-      background: $cozy-dark-blue;
-      color: $cozy-white;
-      border-color: $cozy-dark-blue;
+    &::after {
+      float: right;
+      margin-top: 0.35rem;
+    }
+  }
+
+  &__menu {
+    width: 100%;
+    font-size: 0.85rem;
+    min-width: unset;
+
+    .dropdown-item {
+      font-weight: 600;
+      color: $cozy-dark-blue;
 
-      &:hover {
-        background: $cozy-darkest-blue;
+      &.active {
+        background: $cozy-dark-blue;
+        color: $cozy-white;
       }
     }
   }

content/en/blog/2024-04-05-diy-create-your-own-cloud-with-kubernetes-part-1/index.md

@@ -170,7 +170,7 @@ two years ago was entirely built using this approach. But unfortunately, it does
 deploy your very first parent cluster that will hold the others. So now you have prepared a
 solution that will help you do this the same using PXE approach.
 
-Essentially, all you need to do is [run temporary]({{% ref "/docs/v1/install/talos/pxe" %}})
+Essentially, all you need to do is [run temporary]({{% ref "/docs/v1.0/install/talos/pxe" %}})
 **DHCP** and **PXE** servers inside containers. Then your nodes will boot from your
 image, and you can use a simple Debian-flavored script to help you bootstrap your nodes.
 

content/en/blog/2024-04-05-diy-create-your-own-cloud-with-kubernetes-part-2/index.md

@@ -27,7 +27,7 @@ project and development team.
 Virtual machines are the primary means of isolating tenants from each other in a cloud environment.
 In virtual machines, users can execute code and programs with administrative privilege, but this
 doesn't affect other tenants or the environment itself. In other words, virtual machines allow to
-achieve [hard multi-tenancy isolation]({{% ref "/docs/v1/guides/concepts#tenant-system" %}}), and run
+achieve [hard multi-tenancy isolation]({{% ref "/docs/v1.0/guides/concepts#tenant-system" %}}), and run
 in environments where tenants do not trust each other.
 
 ## Virtualization technologies in Kubernetes

content/en/docs/_index.md

@@ -10,9 +10,9 @@ menu:
     weight: 40
 ---
 
-**New users:** Start with [v1 documentation](/docs/v1/) — the current stable release.
+**New users:** Start with [v1.2 documentation](/docs/v1.2/) — the current stable release.
 
-**Existing v0.4x users:** Continue with [v0 documentation](/docs/v0/) until you're ready to [upgrade](/docs/v1/operations/upgrades/).
+**Existing v0.4x users:** Continue with [v0 documentation](/docs/v0/) until you're ready to [upgrade](/docs/v1.2/operations/upgrades/).
 
 ### Check Your Current Version
 
@@ -22,10 +22,10 @@ If you have an existing installation, run:
 kubectl get deployment -n cozy-system
 ```
 
-- **v1:** You will see a `cozystack-operator` deployment.
+- **v1.x:** You will see a `cozystack-operator` deployment.
 - **v0:** You will see a `cozystack` deployment (the legacy installer).
-- **Namespace not found:** Cozystack is not installed — start with [v1](/docs/v1/).
+- **Namespace not found:** Cozystack is not installed — start with [v1.2](/docs/v1.2/).
 
 **Additional Resources:**
 - [Release notes](https://github.com/cozystack/cozystack/releases)
-- [v0 to v1 upgrade guide](/docs/v1/operations/upgrades/)
+- [v0 to v1.x upgrade guide](/docs/v1.2/operations/upgrades/)

content/en/docs/v1/.gitkeep content/en/docs/v1.0/.gitkeepcontent/en/docs/v1/.gitkeep renamed to content/en/docs/v1.0/.gitkeep

@@ -0,0 +1,18 @@
+---
+title: "Cozystack v1.0 Documentation"
+linkTitle: "Cozystack v1.0"
+description: "Free PaaS platform and framework for building clouds"
+taxonomyCloud: []
+cascade:
+  type: docs
+weight: 30
+aliases:
+  - /docs/v1.0/reference
+  - /docs/v1/
+---
+
+Cozystack is a free PaaS platform and framework for building clouds
+
+With Cozystack, you can transform your bunch of servers into an intelligent system with a simple REST API for spawning Kubernetes clusters, Database-as-a-Service, virtual machines, load balancers, HTTP caching services, and other services with ease.
+
+You can use Cozystack to build your own cloud or to provide a cost-effective development environments.

content/en/docs/v1.0/_index.md

@@ -5,6 +5,6 @@ description: ""
 weight: 50
 aliases:
   - /docs/reference/applications/clickhouse
-  - /docs/v1/reference/applications/clickhouse
+  - /docs/v1.0/reference/applications/clickhouse
 ---