From 3a034712f6af7353e9c9f441e3d2bbdf8731af2d Mon Sep 17 00:00:00 2001
From: trapexit <trapexit@spawn.link>
Date: Thu, 8 May 2025 19:53:54 -0500
Subject: [PATCH] Add versioning to docs using 'mike'

---
 .github/workflows/mkdocs.yml | 42 +++++++++++++++++++++++++++---------
 mkdocs/README.md             |  4 ++--
 mkdocs/mkdocs.yml            |  5 ++++-
 3 files changed, 38 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml
index 509cdefd..d9cbe959 100644
--- a/.github/workflows/mkdocs.yml
+++ b/.github/workflows/mkdocs.yml
@@ -3,21 +3,43 @@ on:
   push:
     branches:
       - master
+    tags:
+      - '*'
+      
 permissions:
   contents: write
+  
 jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
       - name: Configure Git Credentials
         run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-      - run: pip install --no-cache-dir mkdocs mkdocs-material pymdown-extensions
-        working-directory: ./mkdocs
-      - run: mkdocs gh-deploy --force
-        working-directory: ./mkdocs
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Install dependencies
+        working-directory: ./mkdocs      
+        run: |
+          pip install --no-cache-dir mkdocs mkdocs-material pymdown-extensions mike
+        
+      - name: Deploy docs
+        working-directory: ./mkdocs      
+        env:
+          REF_TYPE: ${{ github.ref_type }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          if [ "$REF_TYPE" = "tag" ]; then
+            mike deploy --push --update-aliases "$REF_NAME" latest
+            mike set-default --push latest
+          elif [ "$REF_TYPE" = "branch" ] && [ "$REF_NAME" = "master" ]; then
+            mike deploy --push master
+          fi
diff --git a/mkdocs/README.md b/mkdocs/README.md
index 58c02142..43116f7b 100644
--- a/mkdocs/README.md
+++ b/mkdocs/README.md
@@ -5,8 +5,8 @@
 ```bash
 python3 -m venv venv
 source venv/bin/activate
-pip3 install --no-cache-dir mkdocs mkdocs-material pymdown-extensions
-mkdocs serve
+pip3 install --no-cache-dir mkdocs mkdocs-material pymdown-extensions mike
+mike serve
 ```
 
 ## References
diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml
index a88f3e9a..42b71910 100644
--- a/mkdocs/mkdocs.yml
+++ b/mkdocs/mkdocs.yml
@@ -7,7 +7,10 @@ edit_uri: edit/master/mkdocs/docs/
 docs_dir: docs
 plugins:
   - search
-  - tags
+  - mike
+extra:
+  version:
+    provider: mike
 theme:
   name: material
   logo: logo.png