synapse/.github/workflows/docs-pr.yaml

name: Prepare documentation PR preview

on:
  pull_request:
    paths:
      - docs/**
      - book.toml
      - .github/workflows/docs-pr.yaml
      - scripts-dev/schema_versions.py

jobs:
  pages:
    name: GitHub Pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # Fetch all history so that the schema_versions script works.
          fetch-depth: 0

      - name: Setup mdbook
        uses: peaceiris/actions-mdbook@ee69d230fe19748b7abf22df32acaa93833fad08 # v2.0.0
        with:
          mdbook-version: '0.4.17'

      - name: Setup python
        uses: actions/setup-python@v5
        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: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: book
          path: book
          # We'll only use this in a workflow_run, then we're done with it
          retention-days: 1

  link-check:
    name: Check links in documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup mdbook
        uses: peaceiris/actions-mdbook@ee69d230fe19748b7abf22df32acaa93833fad08 # v2.0.0
        with:
          mdbook-version: '0.4.17'

      - name: Setup htmltest
        run: |
          wget https://github.com/wjdp/htmltest/releases/download/v0.17.0/htmltest_0.17.0_linux_amd64.tar.gz
          echo '775c597ee74899d6002cd2d93076f897f4ba68686bceabe2e5d72e84c57bc0fb  htmltest_0.17.0_linux_amd64.tar.gz' | sha256sum -c
          tar zxf htmltest_0.17.0_linux_amd64.tar.gz

      - name: Test links with htmltest
        # Build the book with `./` as the site URL (to make checks on 404.html possible)
        # Then run htmltest (without checking external links since that involves the network and is slow).
        run: |
          MDBOOK_OUTPUT__HTML__SITE_URL="./" mdbook build
          ./htmltest book --skip-external