docs(ci): Add versioning support without using 'mike'

It seems it may have be simpler to just use 'mike'..

Additionally squashes related commits providing minor fixes + improvements:

- Use a job dependency (`needs`) to avoid `push` event race conditions due to parallel jobs.
- Improve workflow file documentation via inline comments.
- Make ShellCheck linting happy.
- `chown` doesn't seem to work unless on the default branch for CI. Opted to use the docker `--user` approach instead.

.github/workflows/deploy-docs.yml

@@ -8,11 +8,18 @@ on:
     paths:
       - '.github/workflows/deploy-docs.yml'
       - 'docs/**'
+    # Responds to tags being pushed (branches and paths conditions above do not apply to tags).
+    # Takes a snapshot of the docs from the tag (unaffected by branch or path restraints above),
+    # Stores build in a subdirectory with name matching the git tag `v<MAJOR>.<MINOR>` substring:
+    tags:
+      - 'v[0-9]+.[0-9]+*'
 
-# Jobs will run shell commands from this subdirectory:
+env:
-defaults:
+  # Default docs version to build and deploy:
-  run:
+  DOCS_VERSION: edge
-    working-directory: docs
+  # Assign commit authorship to official Github Actions bot when pushing to the `gh-pages` branch:
+  GIT_USER: 'github-actions[bot]'
+  GIT_EMAIL: '41898282+github-actions[bot]@users.noreply.github.com'
 
 jobs:
   deploy:
@@ -21,13 +28,77 @@ jobs:
     steps:
       - uses: actions/checkout@v2
 
+      - name: 'Check if deploy is for a `v<major>.<minor>` tag version instead of `edge`'
+        if: startsWith(github.ref, 'refs/tags/')
+        working-directory: docs
+        run: |
+          DOCS_VERSION=$(grep -oE 'v[0-9]+\.[0-9]+' <<< "${GITHUB_REF}")
+          echo "DOCS_VERSION=${DOCS_VERSION}" >> "${GITHUB_ENV}"
+
+          # Docs should build referencing the tagged version instead:
+          sed -i "s|^\(site_url:.*\)edge|\1${DOCS_VERSION}|" mkdocs.yml
+
       - name: 'Build with mkdocs-material via Docker'
-        run: docker run --rm -v ${PWD}:/docs squidfunk/mkdocs-material build --strict
+        working-directory: docs
+        # --user is required for build output file ownership to match the CI user instead of the containers internal user
+        run: docker run --rm --user "$(id -u):$(id -g)" -v "${PWD}:/docs" squidfunk/mkdocs-material build --strict
+
+      - name: 'If a tagged version, fix canonical links and remove `404.html`'
+        if: startsWith(github.ref, 'refs/tags/')
+        working-directory: docs/site
+        run: |
+          # 404 is not useful due to how Github Pages implement custom 404 support:
+          # (Note the edge 404.html isn't useful either as it's not copied to the `gh-pages` branch root)
+          rm 404.html
+
+          # Replace '${DOCS_VERSION}' (defaults to 'edge') in the 'canonical' link element of HTML files,
+          # with the tagged docs version:
+          find . -type f -name "*.html" -exec \
+            sed -i "s|^\(.*<link rel=\"canonical\".*\)${DOCS_VERSION}|\1edge|" \
+            {} +
 
       - name: 'Deploy to Github Pages'
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build directory contents to publish to the `gh-pages` branch:
           publish_dir: ./docs/site
-          user_name: 'github-actions[bot]'
+          # Directory to place `publish_dir` contents on the `gh-pages` branch:
-          user_email: '41898282+github-actions[bot]@users.noreply.github.com'
+          destination_dir: ${{ env.DOCS_VERSION }}
+          user_name: ${{ env.GIT_USER }}
+          user_email: ${{ env.GIT_EMAIL }}
+
+  add-version-to-docs:
+    name: 'Update `versions.json` if necessary'
+    runs-on: ubuntu-20.04
+    if: startsWith(github.ref, 'refs/tags/')
+    # Avoid race condition with pushing to `gh-pages` branch by waiting for `deploy` to complete first
+    needs: deploy
+    steps:
+      - name: 'Checkout the tagged commit (shallow clone)'
+        uses: actions/checkout@v2
+
+      - name: 'Checkout the docs deployment branch to a subdirectory'
+        uses: actions/checkout@v2
+        with:
+          ref: gh-pages
+          path: gh-pages
+
+      # Updates `env.DOCS_VERSION` to the tag version; if invalid exits job early.
+      - name: 'Ensure `versions.json` has `v<major>.<minor>` substring from tag name'
+        id: add-version
+        continue-on-error: true
+        working-directory: gh-pages
+        run: '../.github/workflows/scripts/docs/update-versions-json.sh'
+
+      # If an actual change was made to `versions.json`, commit and push it.
+      # Otherwise the step is skipped instead of reporting job failure.
+      - name: 'Push update for `versions.json`'
+        if: ${{ steps.add-version.outcome == 'success' }}
+        working-directory: gh-pages
+        run: |
+          git config user.name ${{ env.GIT_USER }}
+          git config user.email ${{ env.GIT_EMAIL }}
+          git add versions.json
+          git commit -m "chore: Add ${{ env.DOCS_VERSION }} to version selector list"
+          git push

.github/workflows/scripts/docs/update-versions-json.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+# CI ENV `GITHUB_REF` from Github Actions CI provides the tag or branch that triggered the build
+# See `github.ref`: https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context
+# https://docs.github.com/en/actions/reference/environment-variables
+function _update-versions-json {
+  # Extract the version tag, truncate `<PATCH>` version and any suffix beyond it.
+  local MAJOR_MINOR
+  MAJOR_MINOR=$(grep -oE 'v[0-9]+\.[0-9]+' <<< "${GITHUB_REF}")
+  # Github Actions CI method for exporting ENV vars to share across a jobs steps
+  # https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-environment-variable
+  echo "DOCS_VERSION=${MAJOR_MINOR}" >> "${GITHUB_ENV}"
+
+  if [[ -z "${MAJOR_MINOR}" ]]
+  then
+    echo "Could not extract valid \`v<MAJOR>.<MINOR>\` substring, exiting.."
+    exit 1
+  fi
+
+  local VERSIONS_JSON='versions.json'
+  local IS_VALID
+  IS_VALID=$(jq '.' "${VERSIONS_JSON}")
+
+  if [[ ! -f "${VERSIONS_JSON}" ]] || [[ -z "${IS_VALID}" ]]
+  then
+    echo "'${VERSIONS_JSON}' doesn't exist or is invalid. Creating.."
+    echo '[{"version": "edge", "title": "edge", "aliases": []}]' > "${VERSIONS_JSON}"
+  fi
+
+
+  # Only add this tag version the first time it's encountered:
+  local VERSION_EXISTS
+  VERSION_EXISTS=$(jq --arg version "${MAJOR_MINOR}" '[.[].version == $version] | any' "${VERSIONS_JSON}")
+
+  if [[ "${VERSION_EXISTS}" == "true" ]]
+  then
+    echo "${MAJOR_MINOR} docs are already supported. Nothing to change, exiting.."
+    exit 1
+  else
+    echo "Added support for ${MAJOR_MINOR} docs."
+    # Add any logic here if you want the version selector to have a different label (`title`) than the `version` URL/subdirectory.
+    local TITLE=${TITLE:-${MAJOR_MINOR}}
+
+    # Assumes the first element is always the "latest" unreleased version (`edge` for us), and then newest version to oldest.
+    # `jq` takes the first array element of array as slice, concats with new element, then takes the slice of remaining original elements to concat.
+    # Thus assumes this script is always triggered by newer versions, no older major/minor releases as our build workflow isn't setup to support rebuilding older docs.
+    local UPDATED_JSON
+    UPDATED_JSON=$(jq --arg version "${MAJOR_MINOR}" --arg title "${TITLE}" \
+      '.[:1] + [{version: $version, title: $title, aliases: []}] + .[1:]' \
+      "${VERSIONS_JSON}"
+    )
+
+    # See `jq` FAQ advising this approach to update file:
+    # https://github.com/stedolan/jq/wiki/FAQ
+    echo "${UPDATED_JSON}" > tmp.json && mv tmp.json "${VERSIONS_JSON}"
+  fi
+}
+
+_update-versions-json

docs/mkdocs.yml

@@ -17,6 +17,13 @@ theme:
     - navigation.tabs
     - navigation.expand
 
+# We do not use `mike`, but enabling this will enable the version selector UI.
+# It references `versions.json` on `gh-pages` branch,
+# however we have a basic setup that only matches `version` to a subdirectory.
+extra:
+  version:
+    provider: mike
+
 markdown_extensions:
   - toc:
       permalink: ⚓︎