5.3: the documentation site, MkDocs on GitHub Pages under webauthn-doc.spomky-labs.com

.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+
+[*.{md,yml,yaml,css,json}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

.gitbook.yaml

@@ -0,0 +1,7 @@
+# GitBook serves the domain until it points to GitHub Pages. The pages moved to docs/ for MkDocs, and this
+# tells GitBook where they are. It goes away with the GitBook space.
+root: ./docs/
+
+structure:
+  readme: README.md
+  summary: SUMMARY.md

.github/workflows/check.yml

@@ -0,0 +1,38 @@
+name: Check
+
+on:
+    pull_request:
+    workflow_dispatch:
+
+# MkDocs 2.0 is announced as backward incompatible with every plugin and theme, so the toolchain is pinned
+# to the 1.x line in requirements.txt and the two notices about it are silenced: they are news about the
+# ecosystem, not findings about this site.
+env:
+    NO_MKDOCS_2_WARNING: 'true'
+    DISABLE_MKDOCS_2_WARNING: 'true'
+
+permissions:
+    contents: read
+
+jobs:
+    build:
+        name: Strict build
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v5
+              with:
+                  fetch-depth: 0
+
+            - uses: actions/setup-python@v6
+              with:
+                  python-version: '3.13'
+                  cache: pip
+                  cache-dependency-path: requirements.txt
+
+            - name: Install the toolchain
+              run: pip install -r requirements.txt
+
+            # --strict turns every warning into an error: a broken internal link, an anchor that does not
+            # exist, a page absent from the navigation or a page in the navigation that does not exist.
+            - name: Build
+              run: mkdocs build --strict

.github/workflows/default-branch.yml

@@ -0,0 +1,73 @@
+name: Default branch
+
+# A new version branch becomes the default branch of the repository, so that a clone and the "edit this
+# page" links land on the newest documentation. Changing the default branch is an administration
+# permission, which the token of Actions cannot be granted: it needs a personal access token with the
+# "repo" scope, in the DEFAULT_BRANCH_TOKEN secret. Without it the workflow does nothing.
+on:
+    create:
+    workflow_dispatch:
+
+jobs:
+    switch:
+        if: github.event_name == 'workflow_dispatch' || github.event.ref_type == 'branch'
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+        env:
+            GH_TOKEN: ${{ secrets.DEFAULT_BRANCH_TOKEN }}
+        steps:
+            - name: Is the token available?
+              id: token
+              run: |
+                  if [ -z "${GH_TOKEN}" ]; then
+                    echo "DEFAULT_BRANCH_TOKEN is not set, nothing to do."
+                    echo "available=false" >> "$GITHUB_OUTPUT"
+                  else
+                    echo "available=true" >> "$GITHUB_OUTPUT"
+                  fi
+
+            - name: The version of the branch that was created
+              id: created
+              if: steps.token.outputs.available == 'true'
+              run: |
+                  ref="${GITHUB_REF#refs/heads/}"
+                  version="${ref#v}"
+                  version="${version%.x}"
+                  if [[ ! "$version" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+                    echo "The branch '$ref' is not a version, nothing to do."
+                    echo "valid=false" >> "$GITHUB_OUTPUT"
+                    exit 0
+                  fi
+                  echo "valid=true" >> "$GITHUB_OUTPUT"
+                  echo "branch=$ref" >> "$GITHUB_OUTPUT"
+                  echo "major=${BASH_REMATCH[1]}" >> "$GITHUB_OUTPUT"
+                  echo "minor=${BASH_REMATCH[2]}" >> "$GITHUB_OUTPUT"
+
+            - name: Is it newer than the default branch?
+              id: decide
+              if: steps.created.outputs.valid == 'true'
+              run: |
+                  current=$(gh repo view "${GITHUB_REPOSITORY}" --json defaultBranchRef --jq .defaultBranchRef.name)
+                  clean="${current#v}"
+                  clean="${clean%.x}"
+                  if [[ ! "$clean" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+                    echo "The current default branch '$current' is not a version, nothing to do."
+                    echo "switch=false" >> "$GITHUB_OUTPUT"
+                    exit 0
+                  fi
+                  major="${{ steps.created.outputs.major }}"
+                  minor="${{ steps.created.outputs.minor }}"
+                  if [ "$major" -gt "${BASH_REMATCH[1]}" ] || { [ "$major" -eq "${BASH_REMATCH[1]}" ] && [ "$minor" -gt "${BASH_REMATCH[2]}" ]; }; then
+                    echo "${major}.${minor} is newer than $clean, switching."
+                    echo "switch=true" >> "$GITHUB_OUTPUT"
+                  else
+                    echo "${major}.${minor} is not newer than $clean, nothing to do."
+                    echo "switch=false" >> "$GITHUB_OUTPUT"
+                  fi
+
+            - name: Switch it
+              if: steps.decide.outputs.switch == 'true'
+              run: |
+                  gh api -X PATCH "repos/${GITHUB_REPOSITORY}" \
+                    -f default_branch="${{ steps.created.outputs.branch }}"

.github/workflows/pages.yml

@@ -0,0 +1,111 @@
+name: Pages
+
+# One version of the site per branch, published by mike into gh-pages: 5.2 is served at /5.2/, and the
+# alias "latest" follows the highest version, which is what the root of the site redirects to. A branch is
+# named 5.2, or 5.2.x like the maintenance branches of a library; 5.x is the next minor. Pages is
+# configured to deploy from the gh-pages branch, root folder.
+on:
+    push:
+        branches:
+            - '[0-9]*.[0-9]*'
+            - '[0-9]*.x'
+        paths-ignore:
+            - '.github/workflows/check.yml'
+    workflow_dispatch:
+
+# MkDocs 2.0 is announced as backward incompatible with every plugin and theme, so the toolchain is pinned
+# to the 1.x line in requirements.txt and the two notices about it are silenced: they are news about the
+# ecosystem, not findings about this site.
+env:
+    NO_MKDOCS_2_WARNING: 'true'
+    DISABLE_MKDOCS_2_WARNING: 'true'
+
+permissions:
+    contents: write
+
+# Two branches pushed at once must not write gh-pages at the same time, and a queued run is never
+# cancelled: it carries a version the other does not.
+concurrency:
+    group: gh-pages
+    cancel-in-progress: false
+
+jobs:
+    deploy:
+        name: Deploy ${{ github.ref_name }}
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v5
+              with:
+                  fetch-depth: 0
+
+            - uses: actions/setup-python@v6
+              with:
+                  python-version: '3.13'
+                  cache: pip
+                  cache-dependency-path: requirements.txt
+
+            - name: Install the toolchain
+              run: pip install -r requirements.txt
+
+            - name: Identify the committer
+              run: |
+                  git config user.name "github-actions[bot]"
+                  git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+            # The version a branch publishes: 5.2.x publishes 5.2, any other name publishes itself.
+            - name: The version of this branch
+              id: version
+              run: |
+                  version="${GITHUB_REF_NAME}"
+                  if [[ "$version" =~ ^[0-9]+\.[0-9]+\.x$ ]]; then
+                    version="${version%.x}"
+                  fi
+                  echo "The branch '${GITHUB_REF_NAME}' publishes the version '$version'."
+                  echo "name=$version" >> "$GITHUB_OUTPUT"
+
+            # The highest version branch of the repository, by version order, in which a "1.x" branch comes
+            # after "1.2" and "1.2.x": it is where the next minor is written. sort -V alone puts "1.x" first,
+            # so each name is sorted by a key where "x" is a large number. Only that branch carries "latest".
+            - name: Is this the newest version?
+              id: newest
+              run: |
+                  git fetch --quiet origin '+refs/heads/*:refs/remotes/origin/*'
+                  newest=$(git for-each-ref --format='%(refname:lstrip=3)' 'refs/remotes/origin/*' \
+                    | grep -E '^[0-9]+\.([0-9]+(\.x)?|x)$' \
+                    | awk '{ key = $0; if (key ~ /^[0-9]+\.x$/) sub(/x$/, "999999", key); else sub(/\.x$/, "", key); print key " " $0 }' \
+                    | sort -V -k1,1 \
+                    | tail -n 1 \
+                    | cut -d' ' -f2)
+                  echo "The newest version branch is '$newest', this one is '${GITHUB_REF_NAME}'."
+                  if [ "$newest" = "${GITHUB_REF_NAME}" ]; then
+                    echo "latest=true" >> "$GITHUB_OUTPUT"
+                  else
+                    echo "latest=false" >> "$GITHUB_OUTPUT"
+                  fi
+
+            - name: Publish this version
+              if: steps.newest.outputs.latest == 'false'
+              run: mike deploy --push --update-aliases "${{ steps.version.outputs.name }}"
+
+            - name: Publish this version as the latest one
+              if: steps.newest.outputs.latest == 'true'
+              run: |
+                  mike deploy --push --update-aliases "${{ steps.version.outputs.name }}" latest
+                  mike set-default --push latest
+
+            # The root of gh-pages is not a version: mike leaves it alone, and it holds what GitHub Pages reads
+            # there. site-root/ in this branch is copied over it: CNAME, the domain of the site, and 404.html,
+            # which sends the addresses of the former GitBook site to the latest version.
+            - name: Publish the root of the site
+              run: |
+                  git fetch --quiet origin gh-pages
+                  git worktree add "${RUNNER_TEMP}/gh-pages" origin/gh-pages
+                  cp -R site-root/. "${RUNNER_TEMP}/gh-pages/"
+                  cd "${RUNNER_TEMP}/gh-pages"
+                  git add --all
+                  if git diff --cached --quiet; then
+                    echo "The root of the site is up to date."
+                  else
+                    git commit --quiet -m "Publish the root of the site from ${GITHUB_REF_NAME}"
+                    git push origin HEAD:gh-pages
+                  fi

.gitignore

@@ -0,0 +1,6 @@
+/site/
+/.venv/
+/.cache/
+__pycache__/
+.idea/
+.claude/