Add boilerplate for docs versioning

.github/workflows/docs-deploy.yml

@@ -1,33 +1,49 @@
 name: Deploy Docs
 
-# Deploys the docs site to GitHub Pages, which serves
-# docs.lightconeresearch.org (custom domain configured in the repo's
-# Pages settings). The site tracks the *released* CLI, not main:
-# deploys happen on the same trigger as the PyPI publish, so the docs
-# never document behavior that `pip install lightcone-cli` can't
-# deliver yet. For an intermediate deploy (typo fix, clarification),
-# trigger manually from the Actions tab (workflow_dispatch runs
-# against the selected branch, main by default).
+# Deploys a versioned snapshot of the docs to the gh-pages branch via
+# mike; GitHub Pages serves that branch as docs.lightconeresearch.org
+# (Settings → Pages must be set to "Deploy from a branch" / gh-pages).
+# Each version lives under its own subdirectory (/0.4.1/, /0.5.0/, …)
+# with the `latest` alias tracking the newest release, so old versions
+# stay accessible after a new one ships.
+#
+# The site tracks the *released* CLI, not main: deploys happen on the
+# same trigger as the PyPI publish, so the docs never document behavior
+# that `pip install lightcone-cli` can't deliver yet. For an
+# intermediate deploy (typo fix, clarification), trigger manually from
+# the Actions tab — workflow_dispatch runs against the selected ref and
+# redeploys the snapshot for the given version (defaults to the latest
+# tag reachable from that ref).
 
 on:
   release:
     types: [published]
   workflow_dispatch:
+    inputs:
+      version:
+        description: "Docs version to (re)deploy, e.g. 0.4.1 (empty: latest tag on the selected ref)"
+        required: false
+        default: ""
 
+# mike commits and pushes to the gh-pages branch.
 permissions:
-  contents: read
-  pages: write
-  id-token: write
+  contents: write
 
+# Deploys append commits to gh-pages — queue them, never cancel one
+# mid-push.
 concurrency:
-  group: pages
-  cancel-in-progress: true
+  group: docs-deploy
+  cancel-in-progress: false
 
 jobs:
-  build:
+  deploy:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          # mike needs the gh-pages branch, and version resolution
+          # needs tags — fetch everything.
+          fetch-depth: 0
 
       - name: Set up uv
         uses: astral-sh/setup-uv@v6
@@ -38,21 +54,28 @@ jobs:
       - name: Install docs dependencies
         run: uv sync --group docs
 
-      - name: Build docs
-        run: uv run zensical build
+      - name: Resolve docs version
+        id: version
+        env:
+          INPUT_VERSION: ${{ inputs.version }}
+        run: |
+          if [ -n "$INPUT_VERSION" ]; then
+            v="$INPUT_VERSION"
+          elif [ "${{ github.event_name }}" = "release" ]; then
+            v="${GITHUB_REF_NAME#v}"
+          else
+            v="$(git describe --tags --abbrev=0)"
+            v="${v#v}"
+          fi
+          echo "version=$v" >> "$GITHUB_OUTPUT"
+          echo "Deploying docs version $v"
 
-      - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: site/
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
-  deploy:
-    needs: build
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deploy.outputs.page_url }}
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deploy
-        uses: actions/deploy-pages@v4
+      - name: Deploy versioned docs to gh-pages
+        run: |
+          uv run mike deploy --push --update-aliases "${{ steps.version.outputs.version }}" latest
+          uv run mike set-default --push latest

CLAUDE.md

@@ -68,6 +68,14 @@ tests/                      # pytest — mirrors src/ structure
 pyproject.toml              # hatchling + hatch-vcs, ASTRA + Snakemake as deps
 ```
 
+## Documentation versioning (mike)
+
+The whole docs site is versioned with [mike](https://github.com/squidfunk/mike) — specifically squidfunk's fork, which Zensical's versioning provider depends on. Each release deploys a full copy of the site to a subdirectory of the `gh-pages` branch (`/0.0.9/`, `/latest/`, etc.). Mike is enabled via `[project.extra.version] provider = "mike"` in `zensical.toml`; the version dropdown in the header is rendered natively.
+
+Release flow: `.github/workflows/docs-deploy.yml` runs on every published release — it runs `mike deploy --push --update-aliases X.Y.Z latest` (version taken from the tag) followed by `mike set-default --push latest`, so the bare site root always redirects to `/latest/`. For an intermediate redeploy of an existing version, trigger the workflow manually from the Actions tab. The `just docs-deploy` / `docs-set-default` / `docs-versions` / `docs-delete-version` recipes wrap the same mike commands for local use.
+
+Hosting: mike pushes to `gh-pages`. GitHub Pages (which serves docs.lightconeresearch.org) must be configured to "Deploy from a branch" / `gh-pages` in the repo's Pages settings, not via the Actions artifact deploy. Without this, `mike deploy` runs successfully but the site doesn't pick up versioned URLs in production.
+
 ## Development Commands
 
 ```bash

justfile

@@ -67,6 +67,21 @@ docs-serve-port port="8080": docs-install
 docs-clean:
     rm -rf site/
 
+# Deploy a versioned snapshot of the docs to gh-pages via mike, updating
+# the named alias (default: latest). Run after `just release`.
+docs-deploy version alias='latest': docs-install
+  uv run mike deploy --push --update-aliases {{version}} {{alias}}
+
+docs-set-default alias='latest':
+  uv run mike set-default --push {{alias}}
+
+docs-versions:
+  uv run mike list
+
+docs-delete-version version:
+  uv run mike delete --push {{version}}
+
+
 # ── Package ────────────────────────────────────────────────────────────────────
 
 # Build the wheel and sdist

pyproject.toml

@@ -54,9 +54,11 @@ dev = [
 ]
 docs = [
     "zensical>=0.0.33",
+    # squidfunk's mike fork — required by zensical's versioning provider.
+    # Not on PyPI; install from git.
+    "mike @ git+https://github.com/squidfunk/mike.git ; python_version >= '3.10'",
 ]
 
-
 [project.scripts]
 lc = "lightcone.cli:main"
 

zensical.toml

@@ -52,6 +52,13 @@ nav = [
   {"ASTRA docs" = "https://astra-spec.org/latest/"},
 ]
 
+# Versioning is handled by mike (squidfunk's fork; see the docs
+# dependency group). Each version of the site is deployed as a
+# subdirectory of the gh-pages branch (e.g. /0.4.1/, /latest/).
+# The version picker is rendered natively in the header.
+[project.extra.version]
+provider = "mike"
+
 [project.theme]
 variant = "modern"
 logo = "assets/logo.svg"