docs: add versioning with mike

.github/workflows/docs.yml

@@ -4,20 +4,99 @@ on:
   push:
     branches:
       - develop
+
+    tags:
+      - 'v*'
+
     paths:
-      - 'docs/*'
+      - 'docs/**'
       - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
 
 permissions:
   contents: write
 
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: false
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
+
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
         with:
-          python-version: 3.x
-      - run: pip install mkdocs-material
-      - run: mkdocs gh-deploy --force
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: pip install mkdocs-material mike
+
+      - name: Fetch gh-pages
+        run: git fetch origin gh-pages --depth=1 || true
+
+      - name: Configure git
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Deploy docs with mike
+        shell: bash
+        run: |
+          set -e
+
+          deploy_version () {
+            local VERSION="$1"
+            local UPDATE_LATEST="${2:-false}"
+
+            VERSION="${VERSION#v}"
+
+            MINOR=$(echo "$VERSION" | sed -E 's/^([0-9]+\.[0-9]+).*/\1/')
+
+            echo "Deploying docs version: $MINOR"
+
+            if [ "$UPDATE_LATEST" = "true" ]; then
+              mike deploy --push --update-aliases "$MINOR" latest
+              return
+            fi
+
+            mike deploy --push "$MINOR"
+          }
+
+          #
+          # Develop branch
+          #
+          if [ "${{ github.ref_type }}" = "branch" ] && [ "${{ github.ref_name }}" = "develop" ]; then
+            echo "Deploying dev docs"
+
+            mike deploy --push dev
+
+            exit 0
+          fi
+
+          #
+          # Release tags
+          #
+          if [ "${{ github.ref_type }}" = "tag" ]; then
+            VERSION="${{ github.ref_name }}"
+
+            if [[ ! "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+              echo "Skipping non-stable release tag: $VERSION"
+              exit 0
+            fi
+
+            deploy_version "$VERSION" true
+
+            echo "Setting default docs version: latest"
+
+            mike set-default --push latest
+
+            exit 0
+          fi
+
+          echo "Unsupported ref"
+          exit 1

docs/overrides/main.html

@@ -0,0 +1,16 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  {% if config.site_url.rstrip("/").endswith("/dev") %}
+    You're viewing the development version.
+    Some features may not be available in a stable release yet.
+    <a href="{{ '../' ~ base_url }}">
+      <strong>Go to the latest stable version.</strong>
+    </a>
+  {% else %}
+    You're not viewing the latest version.
+    <a href="{{ '../' ~ base_url }}">
+      <strong>Click here to go to latest.</strong>
+    </a>
+  {% endif %}
+{% endblock %}

mkdocs.yml

@@ -1,8 +1,12 @@
 site_name: CodeIgniter Settings
 site_description: Settings documentation for CodeIgniter 4 framework
 
+exclude_docs: |
+  overrides/
+
 theme:
   name: material
+  custom_dir: docs/overrides
   logo: assets/flame.svg
   favicon: assets/favicon.ico
   icon:
@@ -35,6 +39,8 @@ theme:
 extra:
   homepage: https://codeigniter.com
   generator: false
+  version:
+    provider: mike
 
   social:
     - icon: material/github