From b56ffc155e065ed08b136d809d2108ce4f3d1451 Mon Sep 17 00:00:00 2001
From: Joachim Wiberg <troglobit@gmail.com>
Date: Thu, 30 Jul 2026 12:04:30 +0200
Subject: [PATCH] doc: version the published User Guide by major release

Finit 5.0 changes the .conf syntax, which has been essentially
unchanged since 1.x.  The published docs track master, so when 5.x
lands, 4.x users lose their reference.

Publish the site under a per-major directory, /4.x/ for now, with
the Material version selector to switch between them.  The selector
only needs mike's file layout -- a versions.json at the site root --
which the deploy job now generates from the version directories in
the pages repo, so mike itself is not needed.

The major comes from AC_INIT and the future 4.x maintenance branch
is already in the workflow triggers, so once 5.0 is on master, doc
fixes on the 4.x branch keep /4.x/ updated.  A root index.html
redirects to the newest version, and a 404.html rewrites
pre-versioned deep links so old bookmarks and search hits land in
the right place.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
---
 .github/workflows/docs.yml | 67 ++++++++++++++++++++++++++++++++++++--
 mkdocs.yml                 |  4 ++-
 2 files changed, 68 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index c8d86659..28e98055 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -4,10 +4,12 @@ on:
   push:
     branches:
       - master
+      - 4.x
     paths:
       - 'doc/**'
       - 'README.md'
       - 'mkdocs.yml'
+      - 'configure.ac'
       - '.github/workflows/docs.yml'
   pull_request:
     types: [opened, synchronize, reopened, labeled]
@@ -15,6 +17,7 @@ on:
       - 'doc/**'
       - 'README.md'
       - 'mkdocs.yml'
+      - 'configure.ac'
       - '.github/workflows/docs.yml'
 
 permissions:
@@ -23,12 +26,21 @@ permissions:
 jobs:
   build:
     runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
           fetch-depth: 0  # Needed for git-revision-date-localized plugin
 
+      - name: Determine docs version
+        id: version
+        run: |
+          version=$(sed -n 's/^AC_INIT(\[Finit\], *\[\([0-9]*\)\..*/\1.x/p' configure.ac)
+          test -n "$version"
+          echo "version=$version" >> $GITHUB_OUTPUT
+
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
@@ -52,9 +64,11 @@ jobs:
           path: site/
 
   deploy:
-    if: github.ref == 'refs/heads/master' && github.event_name == 'push'
+    if: github.event_name == 'push'
     needs: build
     runs-on: ubuntu-latest
+    env:
+      VERSION: ${{ needs.build.outputs.version }}
 
     steps:
       - name: Download site artifact
@@ -79,7 +93,56 @@ jobs:
 
       - name: Sync site to pages repo
         run: |
-          rsync -a --delete --exclude .git site/ pages/
+          rsync -a --delete site/ "pages/$VERSION/"
+
+      - name: Update version index and redirects
+        run: |
+          cd pages/
+
+          # The root holds only version directories and the files
+          # generated below, drop anything else (pre-versioned site)
+          find . -maxdepth 1 ! -name . ! -name .git ! -name CNAME \
+               ! -name '[0-9]*.x' -exec rm -rf {} +
+
+          latest=$(ls -d [0-9]*.x | sort -rV | head -1)
+
+          sep=
+          printf '[' > versions.json
+          for v in $(ls -d [0-9]*.x | sort -rV); do
+              printf '%s{"version": "%s", "title": "%s", "aliases": []}' \
+                     "$sep" "$v" "$v" >> versions.json
+              sep=', '
+          done
+          printf ']\n' >> versions.json
+
+          cat > index.html <<EOF
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <meta charset="utf-8">
+              <meta http-equiv="refresh" content="0; url=$latest/">
+              <link rel="canonical" href="https://finit-project.github.io/$latest/">
+            </head>
+          </html>
+          EOF
+
+          cat > 404.html <<EOF
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <meta charset="utf-8">
+              <title>Finit &mdash; page not found</title>
+              <script>
+                var path = window.location.pathname;
+                if (!/^\/[0-9]+\.x(\/|$)/.test(path))
+                  window.location.replace("/$latest" + path);
+              </script>
+            </head>
+            <body>
+              <p>Page not found.  Try the <a href="/$latest/">latest User Guide</a>.</p>
+            </body>
+          </html>
+          EOF
 
       - name: Commit and push
         run: |
diff --git a/mkdocs.yml b/mkdocs.yml
index 0a8b362c..fe0e34ba 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,6 +1,6 @@
 site_name: User's Guide
 site_description: Fast Init for Linux Systems
-site_url: http://finit-project.github.io
+site_url: https://finit-project.github.io
 repo_url: https://github.com/finit-project/finit
 repo_name: Finit Project
 copyright: Copyright &copy; 2008-2026 Joachim Wiberg
@@ -145,6 +145,8 @@ plugins:
 extra:
   generator: false
   homepage: https://finit-project.github.io/
+  version:
+    provider: mike
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/finit-project/finit