feat: keep multiple versions of github pages (#255)

When we started hosting our own version of the docs, we had to change
the github workflow to build the docs to an org-approved one, which
handled things differently. It was using the "deploy from github
actions" method instead of "deploy from branch".

This PR adds what's necessary to keep all docs versions in [this
branch](https://github.com/famedly/synapse/tree/gh-pages), which allows
the version dropdown picker to work.

Adding/removing folders in this gh-pages branch allows to alter what's
shown in the version picker.

Author: FrenchGithubUser

.github/workflows/docs.yaml

@@ -10,11 +10,6 @@ on:
 
   workflow_dispatch:
 
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
 jobs:
   pre:
     name: Calculate variables for GitHub Pages deployment
@@ -32,7 +27,7 @@ jobs:
 
           case $branch in
               famedly-release/v*)
-                  # strip 'release-' from the name for release branches.
+                  # strip 'famedly-release/v' from the name for release branches.
                   branch="${branch#famedly-release/v}"
                   ;;
               master)
@@ -47,11 +42,16 @@ jobs:
       branch-version: ${{ steps.vars.outputs.branch-version }}
 
   ################################################################################
-  build:
+  pages-docs:
     name: GitHub Pages
     runs-on: ubuntu-latest
     needs:
       - pre
+    concurrency:
+      group: "pages"
+      cancel-in-progress: false
+    permissions:
+      contents: write
 
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -67,15 +67,11 @@ jobs:
 
       - name: Install required tooling
         env:
-            MDBOOK_VERSION: "0.5.2"
+          MDBOOK_VERSION: "0.5.2"
         run: |
           cargo install mdbook-linkcheck mdbook-mermaid
           cargo install mdbook --no-default-features --features search --vers "${{ env.MDBOOK_VERSION }}" --locked
 
-      - name: Setup Pages
-        id: pages
-        uses: actions/configure-pages@v5
-
       - name: Set version of docs
         run: echo 'window.SYNAPSE_VERSION = "${{ needs.pre.outputs.branch-version }}";' > ./docs/website_files/version.js
 
@@ -106,38 +102,51 @@ jobs:
           yq < schema/synapse-config.schema.yaml \
             > book/schema/synapse-config.schema.json
 
-      - name: Restructure for versioning
+      # Deploy to the target directory without wiping other versions.
+      # We use a git worktree so we can merge into gh-pages incrementally,
+      # equivalent to what peaceiris/actions-gh-pages (action used by element/synapse)
+      # does with destination_dir.
+      #
+      # Important: this workflow publishes by pushing commits directly to the
+      # gh-pages branch. The repository's GitHub Pages settings must therefore
+      # be configured to deploy from the gh-pages branch. If Pages is configured
+      # to deploy from "GitHub Actions", this workflow will push commits but the
+      # site will stop publishing.
+      - name: Deploy to gh-pages
         run: |
-          # Create a clean output directory
-          mkdir -p _site/${{ needs.pre.outputs.branch-version }}
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          VERSION="${{ needs.pre.outputs.branch-version }}"
+
+          # Set up a worktree pointing at the gh-pages branch (create it if absent).
+          # Use ls-remote to check existence before fetching so that a missing
+          # branch is treated as "bootstrap" while any real fetch error still
+          # fails the job.
+          if git ls-remote --heads --exit-code origin gh-pages > /dev/null; then
+            git fetch origin gh-pages
+            git worktree add gh-pages-dir origin/gh-pages
+          else
+            # Branch doesn't exist yet, create an empty root commit.
+            EMPTY_TREE=$(git hash-object -t tree /dev/null)
+            INIT_COMMIT=$(git commit-tree "$EMPTY_TREE" -m "Initialize gh-pages")
+            git branch gh-pages "$INIT_COMMIT"
+            git worktree add gh-pages-dir gh-pages
+          fi
 
-          # Move the built book (and schemas) into the versioned subdirectory
-          mv book/* _site/${{ needs.pre.outputs.branch-version }}/
+          # Replace only this version's directory, preserving all others.
+          rm -rf "gh-pages-dir/$VERSION"
+          mkdir -p "gh-pages-dir/$VERSION"
+          cp -r book/. "gh-pages-dir/$VERSION/"
 
-          # Create a root index.html that redirects to the versioned docs
-          # This ensures https://famedly.github.io/synapse/ still works
-          if [ "${{ needs.pre.outputs.branch-version }}" = "latest" ]; then
-            echo '<!DOCTYPE html><meta http-equiv="refresh" content="0; url=latest/index.html">' > _site/index.html
+          # Keep the root redirect pointing at latest/, creating or updating it
+          # whenever latest is deployed or on initial bootstrap.
+          if [ "$VERSION" = "latest" ] || [ ! -f "gh-pages-dir/index.html" ]; then
+            echo '<!DOCTYPE html><meta http-equiv="refresh" content="0; url=latest/index.html">' \
+              > "gh-pages-dir/index.html"
           fi
 
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: ./_site
-
-  deploy:
-    if: ${{ github.ref == 'refs/heads/master' }}
-    # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-    # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
-    concurrency:
-      group: "pages"
-      cancel-in-progress: false
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+          cd gh-pages-dir
+          git add .
+          git diff --staged --quiet || git commit -m "docs: deploy $VERSION"
+          git push origin HEAD:gh-pages