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

@@ -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: |

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 © 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