feat(site): Astro 5 museum-style frontend replacing MkDocs

.github/workflows/ci.yml

@@ -78,3 +78,42 @@ jobs:
 
       - name: Build docs (Chinese)
         run: uv run mkdocs build --strict -f mkdocs.zh.yml
+
+  # ─────────────────────────────────────────────────────────────────────────
+  # New Astro site (site/) — runs alongside the MkDocs build during migration.
+  # When the Astro site replaces MkDocs, drop the `docs-build` job above.
+  # ─────────────────────────────────────────────────────────────────────────
+  site:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: site
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Set up Node
+        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: site/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Unit test — content transforms
+        run: npm run test:sync
+
+      - name: Build (sync + astro + pagefind index)
+        run: npm run build
+        env:
+          # Production build target: GitHub Pages under the repo path.
+          # Keep this in lockstep with astro.config.mjs `base` when it's re-enabled.
+          SITE_BASE: /advanced-agentic-dev-patterns
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
+        with:
+          name: site-dist
+          path: site/dist
+          retention-days: 7

.github/workflows/deploy-site.yml

@@ -0,0 +1,71 @@
+name: Deploy Site (Astro)
+
+# ─────────────────────────────────────────────────────────────────────────
+# Manual-only during the MkDocs → Astro migration.
+#
+# WARNING: `deploy-docs.yml` currently owns the GitHub Pages environment
+# (publishes the MkDocs build at /advanced-agentic-dev-patterns/{en,zh}/).
+# Running THIS workflow will overwrite that deployment with the Astro site.
+#
+# Recommended switchover:
+#   1. `workflow_dispatch` this workflow and verify the deploy URL.
+#   2. Disable `deploy-docs.yml` (rename to .yml.disabled or delete).
+#   3. Re-enable this workflow's `push` trigger (see below).
+# ─────────────────────────────────────────────────────────────────────────
+
+on:
+  workflow_dispatch:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    defaults:
+      run:
+        working-directory: site
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Set up Node
+        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: site/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+        env:
+          SITE_BASE: /advanced-agentic-dev-patterns
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
+        with:
+          path: site/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5

site/.gitignore

@@ -0,0 +1,13 @@
+node_modules
+dist
+.astro
+.env*
+!.env.example
+.DS_Store
+pagefind
+
+# Generated by scripts/sync-content.mjs — rebuilt by predev/prebuild hooks.
+src/content/mm/
+src/content/wiki/
+public/mm/
+public/wiki/

site/astro.config.mjs

@@ -0,0 +1,55 @@
+import { defineConfig } from 'astro/config';
+import mdx from '@astrojs/mdx';
+import react from '@astrojs/react';
+import sitemap from '@astrojs/sitemap';
+import pagefind from 'astro-pagefind';
+import remarkMath from 'remark-math';
+import rehypeKatex from 'rehype-katex';
+import rehypeCallouts from 'rehype-callouts';
+
+// `site` + `base` together tell Astro where the site will live.
+// For GitHub Pages under a repo path, set SITE_BASE=/advanced-agentic-dev-patterns.
+// Local dev leaves SITE_BASE unset so everything serves from `/`.
+// IMPORTANT: keep SITE_BASE in lockstep with scripts/sync-content.mjs —
+// that script bakes the prefix into rewritten markdown URLs.
+const SITE_BASE = (process.env.SITE_BASE ?? '').replace(/\/+$/, '');
+
+export default defineConfig({
+  site: 'https://nanxingw.github.io',
+  base: SITE_BASE || undefined,
+  // GitHub Pages auto-301s paths like /en/mm/cybernetics → /en/mm/cybernetics/
+  // 'ignore' lets both forms work without the extra network hop on nav.
+  trailingSlash: 'ignore',
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en', 'zh'],
+    routing: {
+      prefixDefaultLocale: true,
+      redirectToDefaultLocale: false,
+    },
+  },
+
+  integrations: [
+    react(),
+    mdx(),
+    sitemap(),
+    pagefind(),
+  ],
+
+  markdown: {
+    remarkPlugins: [remarkMath],
+    rehypePlugins: [rehypeKatex, rehypeCallouts],
+    shikiConfig: {
+      themes: { light: 'github-light', dark: 'github-dark-dimmed' },
+      wrap: true,
+      excludeLangs: ['mermaid'],
+    },
+  },
+
+  vite: {
+    resolve: {
+      alias: { '~': '/src' },
+    },
+  },
+});