Centralize tool versions and improve build consistency

.github/PR-PREVIEW.md

@@ -0,0 +1,101 @@
+# PR Preview System
+
+This repository uses GitHub Pages for automated PR preview deployments without any third-party dependencies.
+
+## How It Works
+
+### Architecture
+
+- **Production**: `gh-pages` branch root → https://stlab.github.io/better-code/
+- **PR Previews**: `gh-pages` branch under `pr-preview/[NUMBER]/` → https://stlab.github.io/better-code/pr-preview/123/
+- **Preview Index**: https://stlab.github.io/better-code/pr-preview/ (lists all active previews)
+
+### Workflow
+
+1. **Open PR** → Builds and deploys to `gh-pages:pr-preview/[PR-NUMBER]/`
+2. **Push to PR** → Updates the preview deployment
+3. **Close/Merge PR** → Automatically removes the preview directory
+4. **Merge to main** → Deploys to production (root of gh-pages)
+
+## Features
+
+✅ **Automatic deployment** - No manual steps required  
+✅ **PR comments** - Bot posts preview URL on every PR  
+✅ **Automatic cleanup** - Previews removed when PR closes  
+✅ **No third-party services** - Pure GitHub Pages  
+✅ **Fast builds** - Only builds changed content  
+✅ **Isolated environments** - Each PR gets its own subdirectory  
+
+## File Structure on gh-pages Branch
+
+```
+gh-pages/
+├── index.html              # Production site
+├── chapter-1-intro.html
+├── ...
+└── pr-preview/
+    ├── index.html         # List of all PR previews
+    ├── 123/               # Preview for PR #123
+    │   ├── index.html
+    │   └── ...
+    ├── 124/               # Preview for PR #124
+    │   └── ...
+    └── ...
+```
+
+## Configuration
+
+### Required Permissions
+
+The workflow requires these permissions (already configured):
+- `contents: write` - To push to gh-pages branch
+- `pages: write` - To deploy to GitHub Pages
+- `pull-requests: write` - To comment on PRs
+
+### GitHub Pages Settings
+
+Ensure GitHub Pages is configured to deploy from the `gh-pages` branch:
+1. Go to Settings → Pages
+2. Source: Deploy from a branch
+3. Branch: `gh-pages` / `root`
+
+## Troubleshooting
+
+### Preview not deploying
+
+Check:
+1. Workflow ran successfully in Actions tab
+2. `gh-pages` branch exists and has the preview directory
+3. GitHub Pages is enabled and set to deploy from `gh-pages` branch
+
+### Preview URL 404
+
+- Wait 1-2 minutes after deployment for GitHub Pages to update
+- Check if the directory exists in the `gh-pages` branch
+- Verify the PR number in the URL matches the directory name
+
+### Old previews not cleaning up
+
+- Check if the cleanup workflow ran when PR closed
+- Manually remove with: `git checkout gh-pages && git rm -rf pr-preview/[NUMBER] && git commit && git push`
+
+## Manual Cleanup
+
+To manually remove all PR previews:
+
+```bash
+git checkout gh-pages
+git rm -rf pr-preview/
+git commit -m "Clean up all PR previews"
+git push
+```
+
+To remove a specific preview:
+
+```bash
+git checkout gh-pages
+git rm -rf pr-preview/123
+git commit -m "Remove preview for PR #123"
+git push
+```
+

.github/workflows/cleanup-preview.yml

@@ -0,0 +1,31 @@
+name: Cleanup PR Preview
+
+on:
+  pull_request:
+    types: [closed]
+
+permissions:
+  contents: write
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v6
+        with:
+          ref: gh-pages
+
+      - name: Remove PR preview directory
+        run: |
+          if [ -d "pr-preview/${{ github.event.number }}" ]; then
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git rm -rf pr-preview/${{ github.event.number }}
+            git commit -m "Remove preview for closed PR #${{ github.event.number }}"
+            git push
+            echo "Removed preview for PR #${{ github.event.number }}"
+          else
+            echo "No preview directory found for PR #${{ github.event.number }}"
+          fi
+

.github/workflows/deploy.yml

@@ -1,52 +1,69 @@
-name: Deploy mdBook to GitHub Pages
+name: Build and Deploy mdBook
+# Tool versions are managed in versions.toml at the repository root.
+# To update mdbook or plugin versions, edit versions.toml and the CI will automatically use them.
 
 on:
-  # Runs on pushes targeting the default branch
   push:
     branches: ["main"]
+
+  pull_request:
+    branches: ["main"]
 
-  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
   pages: write
   id-token: write
 
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:
   group: "pages"
   cancel-in-progress: false
 
 jobs:
-  # Build job
   build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+
+      # Cache Rust toolchain and cargo registry
+      - name: Cache Rust
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            ~/.cargo/.crates.toml
+            ~/.cargo/.crates2.json
+          key: ${{ runner.os }}-cargo-${{ hashFiles('versions.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
           
-      - name: Install mdBook
-        run: cargo install mdbook
+      - name: Install mdBook and plugins
+        run: |
+          chmod +x scripts/install-tools.sh
+          ./scripts/install-tools.sh
+      
+      - name: Build with mdBook
+        run: mdbook build ./better-code
 
+      # Only deploy from main branch (push or manual dispatch)
       - name: Setup Pages
+        if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
         id: pages
         uses: actions/configure-pages@v5
 
-      - name: Build with mdBook
-        run: |
-          cd better-code
-          mdbook build
-          
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v4
         with:
           path: ./better-code/book
 
-  # Deployment job
   deploy:
+    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

.tool-versions

@@ -0,0 +1,7 @@
+# Tool versions for asdf version manager
+# See: https://asdf-vm.com/
+#
+# Note: For mdbook and plugin versions, see versions.toml
+# Use the install scripts in better-code/ to install the correct versions
+rust stable
+