CI: publish docs preview site for PRs

.github/workflows/mkdocs.yml

@@ -1,6 +1,13 @@
 name: Publish docs
 on:
   workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/mkdocs.yml"
   push:
     branches:
       - main
@@ -11,9 +18,69 @@ on:
       - "mkdocs.yml"
 
 jobs:
+  docs-preview:
+    name: Publish docs preview
+    runs-on: ubuntu-latest
+    # only pull requests should generate a preview
+    if: github.event.pull_request
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: "refs/pull/${{ github.event.number }}/merge"
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .github/workflows/.python-version
+          cache: pip
+          cache-dependency-path: "docs/requirements.txt"
+
+      - name: Build MkDocs website
+        run: |
+          pip install -r docs/requirements.txt
+          mkdocs build
+
+      - name: Install Netlify CLI
+        run: npm install --location=global netlify-cli@17.x.x
+
+      - name: Deploy Preview to Netlify
+        run: |
+          netlify deploy \
+            --alias="${GITHUB_REPOSITORY#*/}-${{ github.event.number }}" \
+            --auth=${{ secrets.NETLIFY_AUTH_TOKEN }} \
+            --dir="site" \
+            --site=${{ vars.NETLIFY_PREVIEW_APP_SITE_ID }}
+
+      - name: Find existing comment
+        uses: peter-evans/find-comment@v3
+        id: find-comment
+        with:
+          issue-number: ${{ github.event.number }}
+          comment-author: "github-actions[bot]"
+          body-includes: "Preview url: https://"
+
+      - name: Add Netlify link PR comment
+        uses: actions/github-script@v7
+        if: steps.find-comment.outputs.comment-id == ''
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const hostnameSuffix = "compiler-previews.netlify.app"
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `Preview url: https://${context.repo.repo}-${{ github.event.number }}--${hostnameSuffix}`,
+            })
+
   docs:
     name: Publish docs
     runs-on: ubuntu-latest
+    # don't publish for pull requests
+    if: github.event.pull_request == null
     permissions:
       contents: write
     steps: