5.2: 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/

Makefile

@@ -0,0 +1,44 @@
+# The documentation of Beffroi. "make install" once, "make serve" to write, "make check" before a pull
+# request. Every target runs in .venv, created from requirements.txt, with uv when it is installed.
+
+VENV := .venv
+BIN := $(VENV)/bin
+UV := $(shell command -v uv 2>/dev/null)
+
+# News about the MkDocs ecosystem, not findings about this site. requirements.txt pins the 1.x line.
+export NO_MKDOCS_2_WARNING := true
+export DISABLE_MKDOCS_2_WARNING := true
+
+.DEFAULT_GOAL := help
+.PHONY: help install serve build check versions clean
+
+help: ## Show this help
+	@grep -E '^[a-z-]+:.*?## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-10s\033[0m %s\n", $$1, $$2}'
+
+$(BIN)/mkdocs: requirements.txt
+ifdef UV
+	uv venv --allow-existing $(VENV)
+	VIRTUAL_ENV=$(VENV) uv pip install -r requirements.txt
+else
+	python3 -m venv $(VENV)
+	$(BIN)/pip install --upgrade pip
+	$(BIN)/pip install -r requirements.txt
+endif
+	@touch $(BIN)/mkdocs
+
+install: $(BIN)/mkdocs ## Install the toolchain in .venv
+
+serve: install ## Serve the site on http://127.0.0.1:8000, rebuilt as you save
+	$(BIN)/mkdocs serve
+
+build: install ## Build the site into site/
+	$(BIN)/mkdocs build
+
+check: install ## Build strictly: a broken link, a missing anchor or a page outside the navigation fails
+	$(BIN)/mkdocs build --strict
+
+versions: install ## List the versions published on gh-pages
+	$(BIN)/mike list
+
+clean: ## Remove the build and the virtual environment
+	rm -rf site $(VENV)

README.md

@@ -1,18 +1,52 @@
----
-description: >-
-  Seamless Integration with PHP Applications: Our Webauthn Documentation and
-  Tutorials
-layout: landing
----
+# The documentation of WebAuthn Framework
 
-# WebAuthn: Strong Authentication for your PHP applications
+The public documentation of [WebAuthn Framework](https://github.com/web-auth/webauthn-framework), WebAuthn
+and passkeys for PHP and Symfony: the ceremonies, the pure PHP library, the Symfony bundle and the Symfony
+UX components.
 
-Welcome to WebAuthn, the solution for strong authentication on the web. With WebAuthn, you can offer your users a secure, simple, and convenient authentication experience that seamlessly integrates with your PHP or Symfony application.
+Published with [MkDocs](https://www.mkdocs.org/) and
+[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) on GitHub Pages:
+**<https://webauthn-doc.spomky-labs.com/>**
 
-At Spomky-Labs, we are committed to making the web safer for all users. We provide free, libre, and open-source libraries and a Symfony bundle to help you implement strong authentication solutions for your websites and applications.
+## Writing
 
-[WebAuthn](https://www.w3.org/TR/webauthn-2/) is an open-source technology developed by the [World Wide Web Consortium (W3C)](https://www.w3.org/) and is compatible with all modern web browsers. With WebAuthn and PHP, you can offer your users secure authentication without requiring them to remember complex passwords or provide sensitive personal information.
+```bash
+make install   # the toolchain, in .venv, from requirements.txt
+make serve     # http://127.0.0.1:8000, rebuilt as you save
+make check     # the strict build continuous integration runs
+```
 
-WebAuthn is supported by the FIDO Alliance, an organization working to promote open and interoperable strong authentication standards. You can learn more about the FIDO Alliance by visiting their website at [https://fidoalliance.org/](https://fidoalliance.org/).
+`make check` is the gate: a broken internal link, an anchor that does not exist, a page absent from the
+navigation or a navigation entry without a page fails the build.
 
-Explore our documentation to learn more about WebAuthn and how it can help you implement strong authentication in your PHP or Symfony application.
+## Where things are
+
+| Path | What it is |
+|---|---|
+| `mkdocs.yml` | The site: theme, extensions, plugins, and the whole navigation |
+| `docs/` | The pages, one directory per section of the navigation |
+| `docs/assets/stylesheets/` | The look: `slabs-tokens.css`, copied as it is from the Slabs design kit, and `slabs.css`, which applies the guidelines to the theme |
+| `docs/assets/brand/`, `docs/assets/fonts/` | The project mark, the signature, the favicons and the share image of the design kit, and its typefaces (SIL Open Font License) |
+| `docs/overrides/` | Theme partials: the logo, the footer, the link to the repository |
+| `site-root/` | The root of the published site, copied to the root of the `gh-pages` branch: `CNAME`, and the `404.html` that sends the addresses of the former GitBook site to their version |
+| `requirements.txt` | The toolchain, pinned. Continuous integration installs exactly this |
+| `.github/workflows/check.yml` | The strict build, on every pull request |
+| `.github/workflows/pages.yml` | The publication: one version per branch, through mike |
+| `.github/workflows/default-branch.yml` | A new version branch becomes the default branch |
+| `docs/SUMMARY.md`, `.gitbook.yaml` | The GitBook space, until the domain points to GitHub Pages |
+
+How the documentation left GitBook, and the rules every documentation site of Slabs follows, are in
+[Spomky-Labs/docs](https://github.com/Spomky-Labs/docs/blob/main/MIGRATING.md).
+
+## One branch per version
+
+A branch of this repository is a version of the packages: `5.2`, `5.3`, `5.4`, the three minor versions
+the library maintains. A push to one of them publishes it under its own name, and the newest one also
+carries the `latest` alias, which the root of the site redirects to. A fix that applies to several
+versions is made on each of them.
+
+```bash
+git switch -c 5.5 5.4         # from the version it continues
+# in mkdocs.yml, point edit_uri at the new branch
+git push -u origin 5.5        # publishes it, and moves "latest" and the default branch
+```

docs/README.md

@@ -0,0 +1,17 @@
+---
+description: >-
+  Seamless Integration with PHP Applications: Our Webauthn Documentation and
+  Tutorials
+---
+
+# WebAuthn: Strong authentication for your PHP applications
+
+Welcome to WebAuthn, the solution for strong authentication on the web. With WebAuthn, you can offer your users a secure, simple, and convenient authentication experience that seamlessly integrates with your PHP or Symfony application.
+
+At Spomky-Labs, we are committed to making the web safer for all users. We provide free, libre, and open-source libraries and a Symfony bundle to help you implement strong authentication solutions for your websites and applications.
+
+[WebAuthn](https://www.w3.org/TR/webauthn-2/) is an open-source technology developed by the [World Wide Web Consortium (W3C)](https://www.w3.org/) and is compatible with all modern web browsers. With WebAuthn and PHP, you can offer your users secure authentication without requiring them to remember complex passwords or provide sensitive personal information.
+
+WebAuthn is supported by the FIDO Alliance, an organization working to promote open and interoperable strong authentication standards. You can learn more about the FIDO Alliance by visiting their website at [https://fidoalliance.org/](https://fidoalliance.org/).
+
+Explore our documentation to learn more about WebAuthn and how it can help you implement strong authentication in your PHP or Symfony application.