docs: add docs versioning via mike

.crow/docs.yaml

@@ -8,6 +8,30 @@ when:
 
 steps:
   - name: 'Build docs'
+    when:
+      - event: push
+    image: alpine:3.21
+    environment:
+      IS_CI: true
+      MKDOCS_MATERIAL_VERSION: 9.6.11-insiders-4.53.16
+      GH_TOKEN_MKDOCS_MATERIAL:
+        from_secret: gh_token_mkdocs_material
+      CODEBERG_BOT_TOKEN:
+        from_secret: codeberg_bot_token
+    commands:
+      - apk add --no-cache -q git py3-pip cairo just fish go pngquant
+      - python3 -m venv venv
+      - git config --global user.email "admin@crowci.dev"
+      - git config --global user.name "crowci-bot"
+      - git remote set-url origin https://crowci-bot:${CODEBERG_TOKEN}@codeberg.org/crowci/crow.git
+      # build & deploy
+      - just docs-venv-fish
+      - just docs-mike "deploy dev"
+      - mv site/domains site/.domains
+
+  - name: 'Build docs (tag)'
+    when:
+      - event: tag
     image: alpine:3.21
     environment:
       IS_CI: true
@@ -17,12 +41,25 @@ steps:
     commands:
       - apk add --no-cache -q git py3-pip cairo just fish go pngquant
       - python3 -m venv venv
+      - git config --global user.email "admin@crowci.dev"
+      - git config --global user.name "crowci-bot"
+      - git remote set-url origin https://crowci-bot:${CODEBERG_TOKEN}@codeberg.org/crowci/crow.git
+      # build & deploy
       - just docs-venv-fish
-      - just docs-build
+      - just docs-mike "deploy ${CI_COMMIT_TAG} latest"
       - mv site/domains site/.domains
+      - just docs-mike "set-default --push latest"
+
+  - name: Clone gh-pages branch for S3 sync
+    image: alpine:3.21
+    commands:
+      - apk add --no-cache -q git
+      - git clone --branch gh-pages --depth 1 https://codeberg.org/crowci/crow docs_versioned
+      - cd docs_versioned
+      - git checkout gh-pages
 
   - name: s3-sync
-    image: plugins/s3:1.5.2
+    image: woodpeckerci/plugin-s3:1.3.2
     settings:
       bucket: crow-docs-nbg1
       region: nbg1
@@ -31,8 +68,8 @@ steps:
         from_secret: HETZNER_S3_ACCESS_KEY_NBG1
       secret_key:
         from_secret: HETZNER_S3_SECRET_KEY_NBG1
-      source: site/**/*
-      strip_prefix: site/
+      source: docs_versioned/**/*
+      strip_prefix: docs_versioned/
       target: /
     when:
       - event: push

README.md

@@ -68,3 +68,9 @@ The following is a list of notes to keep an overview:
 - Custom dark background color
 - `.explicit-col-width` classes to be able to have tables with fixed column widths.
 - Custom "support" button in `header.html` (including custom css classes `.support-btn`)
+
+### Versioning
+
+A new docs version is published to the `gh-pages` branch via [mike](https://github.com/jimporter/mike) for every release and push to `main` (="dev").
+(`mike` does not allow to use a different branch name than `gh-pages` as it is heavily focused on GitHub Pages.)
+From this branch, the assets will be synced to S3.

docs/overrides/main.html

@@ -0,0 +1,5 @@
+{% extends "base.html" %} {% block outdated %} You are viewing the latest 'dev' version.
+<a href="{{ '../' ~ base_url }}">
+  <strong>Click here to go to latest 'release' version.</strong>
+</a>
+{% endblock %}

mkdocs.yaml

@@ -1,5 +1,5 @@
 site_name: Crow CI
-site_url: https://www.crowci.dev
+site_url: https://www.crowci.dev/
 repo_url: https://codeberg.org/crowci/crow
 repo_name: crowci/crow
 edit_uri: _edit/main/docs/
@@ -62,14 +62,16 @@ theme:
     - navigation.instant.progress
 
 extra:
-  # version:
-  #   provider: mike
+  version:
+    provider: mike
   generator: false
 
 copyright: >
   Copyright © 2025 - 2025 Crow CI
 
 plugins:
+  - mike:
+      alias_type: redirect
   - privacy
   - social:
       cards_layout: default/variant