chore(ci): add docs pr and deploy ci (#305)

This PR introduces:

- the `site/` directory in `./docs` (with `.gitkeep`)
- A workflow (`ci-pr-docs.yml`) for deploying preview PRs using the
vercel CLI and a github action for commenting the URL of this deployed
version
- A workflow (`ci-docs.yml`) for deploying any merges to `main` that
have updates to `./docs/site` to the production vercel environment

The required secrets have been added to the repository settings
(`VERCEL_TOKEN`, `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID`).

task: https://app.asana.com/0/1206208509925075/1206566996089561

.github/workflows/ci-docs.yml

@@ -0,0 +1,28 @@
+name: ci docs
+env:
+  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/site/**'
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+      - name: Install PNPM
+        uses: pnpm/action-setup@v3
+        with:
+          version: 8
+      - name: Install Vercel CLI
+        run: pnpm install --global vercel@latest
+      - name: Pull Vercel Environment Information
+        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
+      - name: Build Project Artifacts
+        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
+      - name: Deploy Project Artifacts to Vercel
+        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

.github/workflows/ci-pr-docs.yml

@@ -0,0 +1,48 @@
+name: ci pr docs
+env:
+  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+on:
+  pull_request:
+    paths:
+      - 'docs/site/**'
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    outputs:
+      url: ${{ steps.deploy.outputs.deployment_url }}
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+      - name: Install PNPM
+        uses: pnpm/action-setup@v3
+        with:
+          version: 8
+      - name: Install Vercel CLI
+        run: pnpm install --global vercel@latest
+      - name: Pull Vercel Environment Information
+        run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
+      - name: Build Project Artifacts
+        run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
+      - name: Deploy Project Artifacts to Vercel
+        id: deploy
+        run: echo "deployment_url=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})" >> $GITHUB_OUTPUT
+  comment:
+    needs: deploy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Comment PR with Deployment URL
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            const deployment_url = '${{ needs.deploy.outputs.url }}';
+            const pr_number = context.payload.pull_request.number;
+            const repository = context.repo.repo;
+            const owner = context.repo.owner;
+            github.rest.issues.createComment({
+              owner: owner,
+              repo: repository,
+              issue_number: pr_number,
+              body: `Docs preview complete 🚀 see it here: ${deployment_url}`
+            });