feat: render PR guides on campdotdev.github.io/guides

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+# Type-checks the renderer and runs the Playwright specs against the fixture guides.
+# The specs build the site from the recorded snapshot in tests/fixtures, so they need no network.
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Typecheck and Playwright
+    runs-on: ubuntu-latest
+    env:
+      ASTRO_TELEMETRY_DISABLED: '1'
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm check
+      - run: pnpm exec playwright install --with-deps chromium
+      - run: pnpm test
+      - if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: playwright-results
+          path: test-results
+          retention-days: 7

.github/workflows/deploy.yml

@@ -0,0 +1,74 @@
+# Builds main's renderer with the guides on the content branch and deploys the site to GitHub Pages.
+# A push to content runs that branch's trigger-deploy.yml, which dispatches this workflow on main.
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Each job grants only the permissions it needs.
+permissions: {}
+
+# One deploy at a time. A newer run waits for the current one instead of canceling it.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # configure-pages reads the Pages site through the API.
+      pages: read
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - name: Check out the guides from the content branch
+        uses: actions/checkout@v7
+        with:
+          ref: content
+          path: content
+          persist-credentials: false
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      # A file at a commit never changes, so cached files never go stale and the cache only grows.
+      # The key is a hash of the guides. A run with the same guides reuses the cache and saves nothing,
+      # and a run with changed guides restores the newest cache and saves it under a new key.
+      - name: Restore the repo file cache
+        uses: actions/cache@v6
+        with:
+          path: .cache/repo-files
+          key: repo-files-${{ hashFiles('content/*/*.md') }}
+          restore-keys: repo-files-
+      - name: Build the site
+        run: pnpm build
+        env:
+          GUIDES_DIR: content
+          REPO_FILE_SOURCE: github
+          REPO_FILE_CACHE: .cache/repo-files
+          GITHUB_TOKEN: ${{ github.token }}
+          ASTRO_TELEMETRY_DISABLED: '1'
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+.astro/
+test-results/
+playwright-report/
+# The deploy workflow checks out the content branch here.
+/content/
+# REPO_FILE_CACHE, when a local build sets it to .cache/repo-files.
+.cache/

.node-version

@@ -0,0 +1 @@
+24

README.md

@@ -1,2 +1,84 @@
 # guides
-Step-by-step guides to campdotdev pull requests, written by the agent that wrote each one.
+
+Step-by-step guides to campdotdev pull requests, written by the agent that wrote each one. The site is https://campdotdev.github.io/guides/.
+
+The repository has two branches with different jobs:
+
+- `main` holds the renderer, an Astro site. Changes reach it through pull requests.
+- `content` holds the guide files, one per pull request at `<repo>/<pr>.md`. Agents push to it directly.
+
+[Guide file format](docs/guide-format.md) documents the guide file. The site serves the same page at `/guides/format/`.
+
+## Run the site locally
+
+You need Node 24 and pnpm 11.
+
+```sh
+pnpm install
+pnpm exec playwright install chromium   # once, for pnpm test
+pnpm dev     # serves the fixture guides at http://localhost:4321/guides/
+pnpm build   # writes the static site and its Pagefind search index to dist/
+pnpm check   # type-checks the project
+pnpm test    # builds the site from the fixtures, serves it, and runs the Playwright specs
+```
+
+Search on the home page reads the index that `pnpm build` writes, so `pnpm dev` has no search results. To try search, run `pnpm build && pnpm preview`.
+
+If another server already holds port 4321, pick another port for the tests, such as `PLAYWRIGHT_PORT=4400 pnpm test`.
+
+To build the published guides, check out `content` into `content/` and read the pull requests' files from GitHub:
+
+```sh
+git worktree add content content
+GUIDES_DIR=content REPO_FILE_SOURCE=github REPO_FILE_CACHE=.cache/repo-files GITHUB_TOKEN=$(gh auth token) pnpm build
+```
+
+## Environment variables
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `GUIDES_DIR` | `tests/fixtures/guides` | The directory the build reads guides from. |
+| `REPO_FILE_SOURCE` | `fixture` | Where the build reads the pull requests' files. `github` reads the GitHub API, and `fixture` reads a recorded snapshot. |
+| `GITHUB_TOKEN` | None | The token the `github` source sends. `REPO_FILE_SOURCE=github` requires it. |
+| `REPO_FILE_FIXTURES` | `tests/fixtures/repo-files` | The snapshot the `fixture` source reads. |
+| `REPO_FILE_CACHE` | None | A directory where the build caches the files it reads from the source, by commit SHA. A later build reads them from there instead of fetching them again. The build logs each file it fetches. |
+| `PLAYWRIGHT_PORT` | `4321` | The port that `pnpm test` serves the build on. |
+
+## Tests
+
+The specs in `tests/e2e` drive the built site in Chromium and assert through roles and accessible names. They read the fixture guides in `tests/fixtures/guides`, which the test suite owns, so the sample guide on `content` can change without breaking them. The search specs query the real Pagefind index that the build writes. Each guide in `tests/fixtures/malformed` must fail the build with an error that names the bad field.
+
+`tests/fixtures/guides/shaders/241.md` names a `baseSha` newer than the merge base, so `merge-base.spec.ts` checks that removed lines come from the merge base.
+
+`tests/fixtures/previous-head` holds the #264 fixture guide pinned to the pull request's previous head, `f09b489`. `reviewed-files.spec.ts` serves a build of it, marks files as reviewed, and then reloads into the main build, the way a guide refresh replaces the page.
+
+The `fixture` source serves each fixture guide's files from `tests/fixtures/repo-files`. The snapshot holds GitHub's comparison of the guide's `baseSha` and `headSha`, which names their merge base, and every changed file at the merge base and the head commit. The tests never touch the network. To record the snapshot for a new fixture guide, run:
+
+```sh
+GITHUB_TOKEN=$(gh auth token) pnpm record-fixture tests/fixtures/guides/<repo>/<pr>.md
+```
+
+The script reads the files through the production `github` source and checks each one against the blob SHA that GitHub lists.
+
+## Deploys
+
+`.github/workflows/deploy.yml` builds `main`'s renderer with the guides on `content` and deploys the site to GitHub Pages. It runs on every push to `main`. Only `main` may deploy to the `github-pages` environment, so a push to `content` runs that branch's `trigger-deploy.yml`, which dispatches `deploy.yml` on `main`.
+
+The workflow keeps `.cache/repo-files` between runs with `actions/cache`, so a deploy fetches only the files that no earlier deploy fetched. The cache key is a hash of the guides on `content`, so the workflow saves a new cache only when a guide changes.
+
+A malformed guide on `content` fails the deploy build, and the site keeps its last good deployment.
+
+`.github/workflows/ci.yml` type-checks the project and runs the Playwright specs on every pull request to `main`.
+
+## Code layout
+
+| Path | Holds |
+| --- | --- |
+| `src/content.config.ts` | The `guides` collection, read from `GUIDES_DIR`. |
+| `src/guide/` | The guide model. It parses and validates a guide file and resolves its pointers to diff hunks. Components never parse Markdown. |
+| `src/repo-files/` | The repo file source: its interface, the `github` and `fixture` sources, the cache, and the switch between them. |
+| `src/components/` | The page components. |
+| `src/client/` | Browser behavior, one module per feature. |
+| `src/highlight.ts` | Syntax highlighting with Shiki, one token list per line. |
+| `docs/guide-format.md` | The guide format reference. |
+| `scripts/record-fixture.ts` | The script that records a fixture snapshot. |

astro.config.mjs

@@ -0,0 +1,12 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+	site: 'https://campdotdev.github.io',
+	base: '/guides',
+	output: 'static',
+	devToolbar: { enabled: false },
+	markdown: {
+		shikiConfig: { themes: { light: 'github-light', dark: 'github-dark' } },
+	},
+});