feat(ci): docs preview and deploy workflow

Author: thekaveman

.github/workflows/mkdocs.yml

@@ -0,0 +1,106 @@
+name: Publish docs
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/mkdocs.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/mkdocs.yml"
+      - "docs/**"
+      - ".markdownlint.yaml"
+      - "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: |
+            "**/pyproject.toml"
+            "docs/requirements.txt"
+
+      - name: Build MkDocs website
+        run: |
+          pip install .[dev] -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:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: .github/workflows/.python-version
+          cache: pip
+          cache-dependency-path: |
+            "**/pyproject.toml"
+            "docs/requirements.txt"
+
+      - name: Install MkDocs requirements
+        run: |
+          pip install .[dev] -r docs/requirements.txt
+
+      - name: Deploy MkDocs website
+        run: |
+          mkdocs gh-deploy --force