From 612608edc902df460a396f1841fb236a5f0b1568 Mon Sep 17 00:00:00 2001
From: Jean Paul Elisa NIYOKWIZERWA
 <140616733+Ndevu12@users.noreply.github.com>
Date: Mon, 17 Aug 2026 22:43:58 +0200
Subject: [PATCH] docs(site): let a release be published by hand, and say where
 the versions start
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The site can version, but nothing has ever produced a second entry:
`gh-pages` holds only `latest`. A version directory is created on a
GitHub Release, and the site landed after v0.6.2 was cut — so the first
one would appear at v0.6.3, with nothing describing the release people
are running today.

The docs workflow can now publish a version on demand (Actions → run the
workflow, give it `0.6.2`), creating the same immutable directory a
release would, with an option to move the `latest` alias onto it. The
input is validated: a leading `v` or anything not shaped like `1.2.3` is
rejected rather than deployed under a name nothing will match.

Publishing 0.6.2 this way is accurate rather than approximate: `src/` is
byte-identical between the v0.6.2 tag and today, so these pages describe
that release exactly. Everything merged since has been documentation.

Older releases are deliberately NOT backfilled. No tag before today
carries an `mkdocs.yml`, so there is nothing of theirs to build, and
republishing today's pages under 0.5.2 would document flags and
behaviour that release does not have — a plausible-looking page that is
wrong is worse than no page. The index now says documented versions
begin at 0.6.2 and points anyone on an older build at `saw --version`
and `-h`, which describe the copy they actually have.

Closes #1475
---
 .github/workflows/docs.yml | 26 ++++++++++++++++++++++++++
 docs/index.md              | 10 ++++++++++
 2 files changed, 36 insertions(+)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index b8d9f18b..67b4e6bf 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -33,7 +33,19 @@ on:
       - '.github/workflows/docs.yml'
   release:
     types: [published]
+  # Publish a version by hand — for backfilling a release that predates this site, or re-cutting
+  # one. Leave `version` empty to refresh `latest` exactly as a push to main does.
   workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish (e.g. 0.6.2). Empty refreshes `latest`.'
+        required: false
+        default: ''
+      set_latest:
+        description: 'Also point the `latest` alias at it'
+        type: boolean
+        required: false
+        default: false
 
 # Least privilege at the top: read-only. Each job widens ONLY what it needs.
 permissions:
@@ -107,12 +119,26 @@ jobs:
         env:
           EVENT: ${{ github.event_name }}
           TAG: ${{ github.event.release.tag_name }}
+          INPUT_VERSION: ${{ inputs.version }}
+          INPUT_SET_LATEST: ${{ inputs.set_latest }}
         run: |
           set -euo pipefail
           if [ "$EVENT" = "release" ]; then
             version="${TAG#v}"
             [ -n "$version" ] || { echo "::error::release event with an empty tag_name"; exit 1; }
             mike deploy --push "$version"
+          elif [ "$EVENT" = "workflow_dispatch" ] && [ -n "${INPUT_VERSION}" ]; then
+            # A hand-published version: same immutable directory a release would create, so a
+            # release that predates this site can be backfilled without re-tagging it.
+            case "$INPUT_VERSION" in
+              [0-9]*.[0-9]*.[0-9]*) : ;;
+              *) echo "::error::version must look like 1.2.3 (no leading v); got '$INPUT_VERSION'"; exit 1 ;;
+            esac
+            if [ "$INPUT_SET_LATEST" = "true" ]; then
+              mike deploy --push --update-aliases "$INPUT_VERSION" latest
+            else
+              mike deploy --push "$INPUT_VERSION"
+            fi
           else
             mike deploy --push --update-aliases latest
             mike set-default --push latest
diff --git a/docs/index.md b/docs/index.md
index c66c6803..fe7a119f 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -31,3 +31,13 @@ keep an organisation's repositories gated.
 
 The package also ships an unrelated uptime monitor, `stayawake-health-check` — see
 [configuration](reference/configuration.md#the-uptime-monitor-configurlsyml).
+
+## Which version you are reading
+
+Each release keeps its own copy of these pages, and the version selector at the top switches
+between them. `latest` follows the current documentation.
+
+Documented versions begin at **0.6.2**. Earlier releases were published before this site existed,
+so there are no pages describing them — rather than reprinting today's documentation under an older
+number, which would describe behaviour those versions do not have. If you are running something
+earlier, `saw --version` and `saw <command> -h` describe the copy you actually have.