feat(astro): complete migration — Vue islands, OCP data layer, 227 specs, GHA

.github/workflows/build.yml

@@ -0,0 +1,92 @@
+name: Build & Test
+
+on:
+  pull_request:
+    paths-ignore:
+      - '_archive-vitepress/**'
+      - 'TODO.astro/**'
+      - 'TODO.improve-website/**'
+      - '**/*.md'
+      - '!src/content/**/*.md'
+  push:
+    branches: [main, feat/astro-migration]
+
+jobs:
+  build:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npx astro check
+
+      - name: Build (must succeed before tests can check dist/)
+        run: npm run build
+
+      - name: Tests (unit + integration)
+        run: npx vitest run
+
+      - name: Verify page count
+        run: |
+          PAGE_COUNT=$(find dist -name "*.html" | wc -l)
+          echo "HTML pages built: $PAGE_COUNT"
+          if [ "$PAGE_COUNT" -lt 250 ]; then
+            echo "::error::Expected ≥250 pages, got $PAGE_COUNT — content collections may be empty"
+            exit 1
+          fi
+
+      - name: Verify content collections produced pages
+        run: |
+          # These files only exist if the content layer loaded successfully.
+          for f in concepts/anatomy/index.html blog/2024-01-15-what-is-pubid/index.html specs/iso-urn/index.html library/api/index.html adopt/guide/index.html; do
+            if [ ! -f "dist/$f" ]; then
+              echo "::error::Missing dist/$f — content collection is empty"
+              exit 1
+            fi
+          done
+
+      - name: Link Checker (lychee)
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: --config lychee.toml --root-dir ./dist "dist/**/*.html"
+          fail: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 14
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,11 +1,36 @@
+# Build output
+dist/
+.output/
+
+# Dependencies
 node_modules/
-.vitepress/dist/
-.vitepress/cache/
-_site/
-.sass-cache/
-.jekyll-cache/
-.jekyll-metadata
-vendor/
+
+# Astro generated
+.astro/
+
+# Env
+.env
+.env.production
+.env.local
+
+# OS
 .DS_Store
-Gemfile.lock
+
+# Logs
+*.log
+npm-debug.log*
+
+# Editor
+.vscode/
+.idea/
+
+# Archived VitePress build artifacts (if anyone builds them locally)
+_archive-vitepress/.vitepress/dist/
+_archive-vitepress/.vitepress/cache/
+_archive-vitepress/_site/
+_archive-vitepress/.jekyll-cache/
+
+# Legacy (preserved for reference)
 TODO*
+!TODO.astro/
+!TODO.improve-website/

.lycheeignore

@@ -1,6 +1,34 @@
+# URLs excluded from lychee link checking. Each entry MUST have an explanatory comment.
+# Format: one PCRE2 regex per line; comments start with #.
+
+# Pubid repo is being moved to github.com/pubid/ org; URL is correct but not
+# yet resolvable.
+^https://github\.com/pubid/pubid/?$
+^https://github\.com/pubid/pubid/issues/?$
+
+# Metanorma blog post being restored; URL is the canonical target.
+^https://www\.metanorma\.org/posts/2022-01-09-nist-pubid/?$
+
+# Relaton blog post being restored; URL is the canonical target.
+^https://www\.relaton\.org/posts/2023-08-23-nist-cswp-pubid/?$
+
+# Adobe.com — HTTP/2 protocol error from lychee's HTTP client; the link is
+# valid for browsers. Excluded until upstream lychee/rustls supports the
+# Adobe TLS configuration cleanly.
+^https://www\.adobe\.com/?$
+
+# Publisher WAFs that block GitHub Actions IP ranges (links are valid for
+# real browsers). 403 from CI does not indicate a broken link.
+^https://www\.ansi\.org/?$
+^https://www\.astm\.org/?$
+^https://www\.csagroup\.org/?$
+^https://www\.iec\.ch/?$
+
+# Local-asset patterns from VitePress era (not used by Astro, but harmless).
 assets
 javascript:.*
-https://twitter.com/RiboseUS
 .*@.*example.com
 (ht|f)tps?://.*\.?example\.(com|org).*
-https://.*\.?pubid\.(com|net|org).*
+^https://www\.w3c\.org/?$
+^https://www\.w3\.org/?$
+^https://www\.3gpp\.org/?$

TODO.astro/01-scaffold-and-config.md

@@ -0,0 +1,78 @@
+# 01 — Scaffold & Config
+
+**Status:** started (this session)
+**Branch:** `feat/astro-migration`
+**Working dir:** `astro-site/` (new subdir; VitePress at root is untouched)
+
+## Goal
+
+A runnable Astro 7 project with Starlight, Tailwind 4, React, and SSG output configured. `astro dev` boots, `astro build` produces `.html` files, and a placeholder home page renders with Tailwind classes applied.
+
+## Acceptance criteria
+
+- [ ] `astro-site/package.json` exists with these deps (versions ≥ the floor listed):
+  - `astro@^7.0.7`
+  - `vite@^8.1.4`
+  - `@astrojs/starlight@^0.41.3`
+  - `@astrojs/react@latest`, `@astrojs/sitemap@latest`, `@astrojs/mdx@latest`
+  - `tailwindcss@^4.3.2`, `@tailwindcss/vite@^4.3.2`
+  - `react@^19`, `react-dom@^19`, `@types/react@^19`
+  - `@fontsource-variable/fraunces`, `@fontsource-variable/inter-tight` (or chosen pair)
+- [ ] `astro-site/astro.config.mjs` configured with:
+  - `site: 'https://www.pubid.com'`
+  - `output: 'static'`
+  - integrations: `starlight()`, `react()`, `mdx()`, `sitemap()`
+  - `vite.plugins: [tailwindcss()]` (the `@tailwindcss/vite` plugin)
+  - `markdown.shikiConfig` matching the brand palette
+- [ ] `astro-site/tsconfig.json` extends `astro/tsconfigs/strict`
+- [ ] `astro-site/src/styles/global.css` does `@import "tailwindcss";` and imports the design tokens from TODO 02
+- [ ] `astro-site/src/pages/index.astro` renders a hero with the PubID logo and headline
+- [ ] `npm run dev` boots on a free port, returns 200 for `/`
+- [ ] `npm run build` produces `astro-site/dist/index.html`
+
+## Implementation notes
+
+### Astro 7 specifics
+
+- Astro 7 stable was released after Starlight 0.34. Starlight 0.41 supports Astro 7 — verified via `npm view @astrojs/starlight peerDependencies`.
+- Use the Content Layer API (`src/content.config.ts`) for collections — replaces `getStaticPaths`-style content fetching for MD/MDX.
+
+### Starlight layout strategy
+
+Starlight ships its own layout. We use it for the docs-shaped sections (Concepts, Library, Specs, Adopt) under route prefixes like `/concepts/*`, `/library/*`, etc. — each gets its own Starlight sidebar via `StarlightRoute` overrides, or we run multiple Starlight instances.
+
+The homepage and publisher pages (which have heavily custom UI) live OUTSIDE Starlight, using our own `BaseLayout.astro`.
+
+### Tailwind 4 via Vite plugin
+
+Tailwind 4 uses the Vite plugin directly — **no `tailwind.config.js` needed**, no PostCSS config. Tokens are declared in CSS via `@theme { --color-accent: ...; }`. Custom utilities via `@utility`.
+
+```css
+@import "tailwindcss";
+@theme {
+  --color-pubid: #2978a1;
+  --font-display: "Fraunces Variable", serif;
+}
+```
+
+### Don't do in this task
+
+- Don't port the actual VitePress components yet (TODO 05–09).
+- Don't migrate content collections yet (TODO 10–15).
+- Don't touch VitePress files at the repo root.
+
+## Inputs / references
+
+- Versions verified via `npm view` (see README.md)
+- Existing VitePress config: `.vitepress/config.ts`
+- Existing custom CSS tokens: `.vitepress/theme/custom.css` lines 7–48
+
+## Outputs
+
+- `astro-site/` directory tree
+- First commit on `feat/astro-migration`
+- A dev server URL the user can open
+
+## Next
+
+→ TODO 02 (design system tokens)