docs.yaml

name: Deploy the documentation

on:
  push:
    branches:
      # For documentation specific to a release
      - "famedly-release/v*"
      # stable docs
      - master

  workflow_dispatch:

jobs:
  pre:
    name: Calculate variables for GitHub Pages deployment
    runs-on: ubuntu-latest
    steps:
      # Figure out the target directory.
      #
      # The target directory depends on the name of the branch
      #
      - name: Get the target directory name
        id: vars
        run: |
          # first strip the 'refs/heads/' prefix with some shell foo
          branch="${GITHUB_REF#refs/heads/}"

          case $branch in
              famedly-release/v*)
                  # strip 'famedly-release/v' from the name for release branches.
                  branch="${branch#famedly-release/v}"
                  ;;
              master)
                  # deploy to "latest" for the master branch.
                  branch="latest"
                  ;;
          esac

          # finally, set the 'branch-version' var.
          echo "branch-version=$branch" >> "$GITHUB_OUTPUT"
    outputs:
      branch-version: ${{ steps.vars.outputs.branch-version }}

  ################################################################################
  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
        with:
          # Fetch all history so that the schema_versions script works.
          fetch-depth: 0

      - name: Caching
        uses: Swatinem/rust-cache@98c8021b550208e191a6a3145459bfc9fb29c4c0 # v2.8.0
        with:
          shared-key: "mdbook"
          save-if: ${{ ! startsWith(github.ref, 'gh-readonly-queue/') }}

      - name: Install required tooling
        env:
          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: Set version of docs
        run: echo 'window.SYNAPSE_VERSION = "${{ needs.pre.outputs.branch-version }}";' > ./docs/website_files/version.js

      - name: Setup python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: "3.x"

      - run: "pip install 'packaging>=20.0' 'GitPython>=3.1.20'"

      - name: Build the documentation
        # mdbook will only create an index.html if we're including docs/README.md in SUMMARY.md.
        # However, we're using docs/README.md for other purposes and need to pick a new page
        # as the default. Let's opt for the welcome page instead.
        run: |
          mdbook build
          cp book/welcome_and_overview.html book/index.html

      - name: Prepare and publish schema files
        run: |
          sudo apt-get update && sudo apt-get install -y yq
          mkdir -p book/schema
          # Remove developer notice before publishing.
          rm schema/v*/Do\ not\ edit\ files\ in\ this\ folder
          # Copy schema files that are independent from current Synapse version.
          cp -r -t book/schema schema/v*/
          # Convert config schema from YAML source file to JSON.
          yq < schema/synapse-config.schema.yaml \
            > book/schema/synapse-config.schema.json

      # 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: |
          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

          # 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/"

          # 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

          cd gh-pages-dir
          git add .
          git diff --staged --quiet || git commit -m "docs: deploy $VERSION"
          git push origin HEAD:gh-pages