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>
2026-09-30 13:02:37 +07:00 · 2026-07-30 12:27:27 +02:00
parent 4596e27eb0
commit b56ffc155e
2 changed files with 68 additions and 3 deletions
@@ -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: |
@@ -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