feat: cut over educates.dev to the redesigned site

.claude/skills/copy-graham-blog-post/SKILL.md

@@ -5,12 +5,13 @@ description: Copies blog posts from Graham Dumpleton's blog (grahamdumpleton.me
 
 # Copy Graham blog post to Educates site
 
-Copy a post (and its images) from [Graham Dumpleton's blog repo](https://github.com/GrahamDumpleton/grahamdumpleton.me) into this repo's `blog/` folder, and rewrite the text from first person singular (I, my) to first person plural (we, our) as the Educates team.
+Copy a post (and its images) from [Graham Dumpleton's blog repo](https://github.com/GrahamDumpleton/grahamdumpleton.me) into this repo's posts collection, `src/content/posts/`, and rewrite the text from first person singular (I, my) to first person plural (we, our) as the Educates team.
 
 ## Source and target
 
 - **Source**: GitHub repo `GrahamDumpleton/grahamdumpleton.me`, path like `src/posts/YYYY/MM/post-slug/` (e.g. `src/posts/2026/02/deploying-educates-yourself`).
-- **Target**: This repo's `blog/` folder. Create a folder named `YYYY-MM-DD-<slug>/` (e.g. `2026-02-26-deploying-educates-yourself`) containing `index.md` and any image files. Use the post's `date` from frontmatter for the folder date, or the path date if needed. Add `<!--truncate -->` after first paragraph. If first paragraph is too short, do it after the second. Also, review the tags to align with those in `blog/tags.yaml` and the topic in the blog.
+- **Target**: a folder `src/content/posts/YYYY-MM-DD-<slug>/` (e.g. `src/content/posts/2026-02-26-deploying-educates-yourself/`) holding `index.md` and the post's image files. The folder date is the post's `date` from its front matter, or the date in the source path if it has none.
+- **Format**: `index.md`. Only a post that uses a component, such as `<AsciinemaPlayer>`, is `index.mdx`.
 
 ## Workflow
 
@@ -49,59 +50,64 @@ In the **body** (not code blocks or image alt text unless they are first-person
 
 Preserve "you" when addressing the reader. Do not change technical wording, code blocks, or link URLs except internal post links.
 
-### 4. Adapt frontmatter
+### 4. Write the front matter
 
-- Keep: `title`, `description`, `date`, `tags`, `image`, `draft`.
-- Add: `slug: <post-slug>` (e.g. `deploying-educates-yourself`).
-- Add: `authors: [graham]`.
-- Remove any frontmatter fields this site does not use (check existing posts in `blog/` for the schema).
-- Remove `daft` and `date` frontmatter fields.
+The posts collection's schema is in `src/content.config.ts`; the build fails on a post that breaks it. Write these keys:
 
+- `title`: from the source.
+- `slug`: the post's slug (e.g. `deploying-educates-yourself`). The post is served at `/blog/<slug>`, and the slug never changes once published.
+- `description`: required. Take the source's description; if it has none, write one or two sentences saying what the reader gets from the post.
+- `date`: the source's date, as `YYYY-MM-DD`.
+- `tags`: keys defined in `src/content/tags.yml` that fit the post's topic (see step 6). A key missing from that file fails the build.
+- `authors: [graham]`. Authors are keys of `src/content/authors.yml`.
+- `draft: true` only for a post that must not publish yet; it then shows in the dev server only.
+
+Leave out every other key of the source, such as `image`. A post gets a generated cover; a picture of its own goes in `cover`, as the path of an image file next to the post.
+
+The post body carries no truncate marker: lists show the `description`.
 
 ### 5. Fix internal links
 
-Replace Graham's post paths with this site's blog paths:
+Replace Graham's post paths with this site's post paths, `/blog/<slug>`, with no trailing slash:
 
-- `/posts/YYYY/MM/slug/` or `/posts/2026/02/teaching-an-ai-about-educates/` → `/blog/<slug>` (e.g. `/blog/teaching-an-ai-about-educates`).
-- Use `/blog/<slug>` consistently (no trailing slash required; add one if the site expects it).
+- `/posts/YYYY/MM/slug/` (e.g. `/posts/2026/02/teaching-an-ai-about-educates/`) → `/blog/<slug>` (e.g. `/blog/teaching-an-ai-about-educates`).
+
+GitHub Pages answers `/blog/<slug>/` with a 404, so every internal link ends without a slash.
 
 ### 6. Adjust tags
 
-- Review tags in frontmatter section to align with the contents of the blog post and tags already defined in `blog/tags.yaml`
+Review the tags against the post's content and the tags defined in `src/content/tags.yml`, and keep only keys from that file.
 
-### 6. Create target folder and files
+### 7. Create target folder and files
 
-- Create `blog/YYYY-MM-DD-<slug>/` (e.g. `blog/2026-02-26-deploying-educates-yourself/`).
-- Write the rewritten content to `blog/YYYY-MM-DD-<slug>/index.md`.
+- Create `src/content/posts/YYYY-MM-DD-<slug>/` (e.g. `src/content/posts/2026-02-26-deploying-educates-yourself/`).
+- Write the rewritten content to `index.md` in that folder.
 - Download each image from `https://raw.githubusercontent.com/GrahamDumpleton/grahamdumpleton.me/main/src/posts/YYYY/MM/<post-slug>/<filename>` into the same folder. Image references in the markdown are relative (e.g. `training-portal.png`), so they resolve correctly.
 
-### 7. Verify
+### 8. Verify
 
 - Confirm all images are present and paths in markdown match filenames.
-- Spot-check that first-person singular in the body has been converted to plural and internal links use `/blog/...`.
+- Spot-check that first-person singular in the body has been converted to plural, and that internal links are `/blog/<slug>` without a trailing slash.
+- Run `npm run build`: it validates the front matter, renders the post at `/blog/<slug>`, and runs the site check.
 
 ## Example
 
 User provides: `https://github.com/GrahamDumpleton/grahamdumpleton.me/tree/main/src/posts/2026/02/deploying-educates-yourself`
 
 - Post slug: `deploying-educates-yourself`.
 - List contents → get `index.md`, `training-portal.png`, `workshop-dashboard.png`.
-- Fetch `index.md`, rewrite I/my → we/our, add `slug` and `authors: [graham]`, change link to previous post to `/blog/teaching-an-ai-about-educates`.
-- Create `blog/2026-02-26-deploying-educates-yourself/index.md` and download the two PNGs into that folder.
+- Fetch `index.md`, rewrite I/my → we/our, write the front matter, change the link to the previous post to `/blog/teaching-an-ai-about-educates`.
+- Create `src/content/posts/2026-02-26-deploying-educates-yourself/index.md` and download the two PNGs into that folder.
 
-## Reference: existing Educates post frontmatter
+## Reference: Educates post front matter
 
 ```yaml
 ---
-title: "..."
-slug: post-slug
-description: "..."
-date: YYYY-MM-DD
-tags: ["educates", "ai"]
+title: "Deploying Educates yourself"
+slug: deploying-educates-yourself
+description: "Educates is open source, not a SaaS. Deploy it yourself, wherever you want."
+date: 2026-02-26
+tags: ["educates", "installation", "local"]
 authors: [graham]
-image: https://opengraph.githubassets.com/1/educates/educates-training-platform
-draft: false
 ---
 ```
-
-Authors are defined in `blog/authors.yml`; `graham` exists. Use the same structure for new posts.

.devcontainer/devcontainer.json

@@ -17,20 +17,19 @@
         }
       },
       "extensions": [
-        "dbaeumer.vscode-eslint",
-        "orta.vscode-jest",
+        "astro-build.astro-vscode",
         "esbenp.prettier-vscode",
         "streetsidesoftware.code-spell-checker"
       ]
     }
   },
   // "forwardPorts": [3000],
   // "containerUser": "vscode",
-  "postCreateCommand": "yarn install",
-  "waitFor": "postCreateCommand", // otherwise automated jest tests fail
+  "postCreateCommand": "npm install",
+  "waitFor": "postCreateCommand",
   "features": {
     "node": {
-      "version": "18"
+      "version": "26"
     },
     "github-cli": "latest"
   }

.dockerignore

@@ -0,0 +1,17 @@
+# The build installs its own dependencies and writes its own output.
+node_modules/
+dist/
+.astro/
+
+# Not part of the site.
+.git
+.github/
+.devcontainer/
+.claude/
+.scratch
+Dockerfile
+.dockerignore
+npm-debug.log*
+.DS_Store
+.env
+.env.*

.github/dependabot.yml

@@ -0,0 +1,30 @@
+# Weekly dependency updates. Minor and patch updates arrive as one pull
+# request per ecosystem; each major update gets a pull request of its own, so
+# a new Astro major is never missed.
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: build
+      include: scope
+    groups:
+      npm-minor-and-patch:
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: ci
+      include: scope
+    groups:
+      actions-minor-and-patch:
+        update-types:
+          - minor
+          - patch

.github/workflows/checks.yaml

@@ -0,0 +1,70 @@
+name: Checks
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: checks-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: Checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      # Node.js at the Volta pin in package.json.
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: package.json
+          cache: npm
+
+      - name: Install dependencies
+        id: install
+        run: npm ci
+
+      # Each check runs even when an earlier one fails, so a pull request
+      # sees every failure at once.
+      - name: Type-check
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: npm run check
+
+      - name: Check formatting
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: npm run format:check
+
+      - name: Build the site
+        id: build
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: npx astro build
+
+      - name: Run the site check
+        if: ${{ !cancelled() && steps.build.outcome == 'success' }}
+        run: npm run site-check
+
+      - name: Run the unit tests
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: npm test
+
+      # Offline, as `npm run link-check` runs it, with lychee.toml's settings.
+      - name: Check internal links
+        if: ${{ !cancelled() && steps.build.outcome == 'success' }}
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: --offline --root-dir "${{ github.workspace }}/dist" 'dist/**/*.html'
+
+      # The pages and thresholds are in lighthouserc.yml.
+      - name: Run Lighthouse
+        if: ${{ !cancelled() && steps.build.outcome == 'success' }}
+        uses: treosh/lighthouse-ci-action@v12
+        with:
+          configPath: ./lighthouserc.yml
+          uploadArtifacts: true

.github/workflows/deploy.yaml

@@ -1,52 +1,48 @@
 name: Deploy to GitHub Pages
 
 on:
-  workflow_dispatch:
   push:
     branches:
       - main
-    # Review gh actions docs if you want to further define triggers, paths, etc
-    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# One deployment at a time; a running deployment finishes before the next.
+concurrency:
+  group: pages
+  cancel-in-progress: false
 
 jobs:
   build:
-    name: Build Docusaurus
+    name: Build the site
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: yarn
+      - uses: actions/checkout@v7
 
-      - name: Install dependencies
-        run: yarn install --frozen-lockfile
-      - name: Build website
-        run: yarn build
+      - name: Read the Node.js version from the Volta pin
+        id: node
+        run: echo "version=$(jq -r .volta.node package.json)" >> "$GITHUB_OUTPUT"
 
-      - name: Upload Build Artifact
-        uses: actions/upload-pages-artifact@v3
+      # Installs the dependencies, runs `npm run build` (the build and the
+      # site check) and uploads dist/ as the Pages artifact.
+      - name: Build the site and upload it
+        uses: withastro/action@v6
         with:
-          path: build
+          node-version: ${{ steps.node.outputs.version }}
 
   deploy:
     name: Deploy to GitHub Pages
     needs: build
-
-    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    runs-on: ubuntu-latest
     permissions:
-      pages: write # to deploy to Pages
-      id-token: write # to verify the deployment originates from an appropriate source
-
-    # Deploy to the github-pages environment
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-
-    runs-on: ubuntu-latest
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5