docs: migrate docs site from Docusaurus to Astro + Starlight

.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(curl -s https://raw.githubusercontent.com/nebari-dev/starlight/main/package.json)",
+      "Bash(curl -s https://api.github.com/repos/nebari-dev/starlight/contents/packages)",
+      "Bash(curl -s https://api.github.com/repos/nebari-dev/starlight/contents/docs)",
+      "Bash(awk '/^diff --git a\\\\/docs\\\\/package.json/,/^diff --git a\\\\/docs\\\\/src\\\\/assets\\\\/logo-dark.svg/' pr127.diff)",
+      "Bash(curl -s https://api.github.com/repos/nebari-dev/starlight/contents/packages/starlight)",
+      "Bash(curl -s https://raw.githubusercontent.com/nebari-dev/starlight/main/packages/starlight/package.json)",
+      "Bash(curl -s https://raw.githubusercontent.com/nebari-dev/starlight/main/docs/package.json)",
+      "Bash(curl -s https://raw.githubusercontent.com/nebari-dev/starlight/main/docs/astro.config.mjs)",
+      "Bash(awk '/^diff --git a\\\\/docs\\\\/tsconfig.json/,0' pr127.diff)",
+      "Bash(nix-shell --run \"which npm; which node; node --version; npm --version\")"
+    ]
+  }
+}

.github/workflows/docs-preview-cleanup.yml

@@ -0,0 +1,40 @@
+name: Docs preview cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-preview-cleanup-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+env:
+  CF_PROJECT: chat-pack
+
+jobs:
+  cleanup:
+    if: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Delete this branch's preview deployments
+        env:
+          CF_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CF_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          BRANCH: ${{ github.event.pull_request.head.ref }}
+        run: |
+          set -euo pipefail
+          base="https://api.cloudflare.com/client/v4/accounts/${CF_ACCOUNT_ID}/pages/projects/${CF_PROJECT}/deployments"
+          ids=$(curl -fsS -H "Authorization: Bearer ${CF_API_TOKEN}" "${base}?env=preview&per_page=100" \
+            | jq -r --arg b "$BRANCH" '.result[] | select(.deployment_trigger.metadata.branch == $b) | .id')
+          if [ -z "$ids" ]; then
+            echo "No preview deployments found for branch '$BRANCH'."
+            exit 0
+          fi
+          for id in $ids; do
+            echo "Deleting preview deployment $id (branch '$BRANCH')"
+            curl -fsS -X DELETE -H "Authorization: Bearer ${CF_API_TOKEN}" "${base}/${id}?force=true" >/dev/null
+          done
+          echo "Cleaned up preview deployments for branch '$BRANCH'."

.github/workflows/docs.yml

@@ -1,14 +1,26 @@
-name: Deploy docs to GitHub Pages
+name: Docs
 
 on:
   push:
-    branches:
-      - main
+    branches: [main]
+    paths: ['docs/**', 'scripts/check-links.sh', '.github/workflows/docs.yml']
   pull_request:
+    paths: ['docs/**', 'scripts/check-links.sh', '.github/workflows/docs.yml']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  PACK_SLUG: chat-pack
 
 jobs:
-  build:
-    name: Build
+  docs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
@@ -17,39 +29,64 @@ jobs:
 
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: 20
+          node-version: '22'
           cache: npm
           cache-dependency-path: docs/package-lock.json
 
-      - name: Install dependencies
+      - name: Install deps
+        working-directory: docs
         run: npm ci
+
+      - name: Install Playwright (mermaid rendering)
         working-directory: docs
+        run: npx playwright install --with-deps chromium
 
-      - name: Run typecheck
-        run: npm run typecheck
+      - name: Unit tests
         working-directory: docs
+        run: npm test
 
-      - name: Build website
-        run: npm run build
+      - name: Compute site, base, and deploy branch
+        id: base
+        env:
+          HEAD_REF: ${{ github.head_ref || github.ref_name }}
+        run: |
+          if [ "${{ github.ref }}" = "refs/heads/main" ]; then
+            echo "site=https://packs.nebari.dev" >> "$GITHUB_OUTPUT"
+            echo "base=/${PACK_SLUG}/" >> "$GITHUB_OUTPUT"
+            echo "branch=main" >> "$GITHUB_OUTPUT"
+          else
+            ALIAS=$(printf '%s' "$HEAD_REF" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g')
+            echo "site=https://${ALIAS}.${PACK_SLUG}.pages.dev" >> "$GITHUB_OUTPUT"
+            echo "base=/" >> "$GITHUB_OUTPUT"
+            echo "branch=${HEAD_REF}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build
         working-directory: docs
+        env:
+          SITE: ${{ steps.base.outputs.site }}
+          BASE: ${{ steps.base.outputs.base }}
+        run: npm run build
+
+      - name: Check internal links
+        env:
+          BASE: ${{ steps.base.outputs.base }}
+        run: SKIP_BUILD=1 bash scripts/check-links.sh
 
-      - name: Upload build artifact
-        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+      - name: Deploy to Cloudflare Pages
+        id: deploy
+        if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
+        uses: cloudflare/wrangler-action@ebbaa1584979971c8614a24965b4405ff95890e0 # v4.0.0
         with:
-          path: docs/build
-
-  deploy:
-    name: Deploy to GitHub Pages
-    needs: build
-    if: github.ref == 'refs/heads/main'
-    permissions:
-      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@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy docs/dist --project-name=${{ env.PACK_SLUG }} --branch=${{ steps.base.outputs.branch }}
+
+      - name: Comment preview URL
+        if: ${{ github.event_name == 'pull_request' && steps.deploy.outcome == 'success' }}
+        uses: thollander/actions-comment-pull-request@24bffb9b452ba05a4f3f77933840a6a841d1b32b # v3.0.1
+        with:
+          comment-tag: docs-preview
+          message: |
+            📄 **Docs preview** for `${{ github.event.pull_request.head.ref }}`:
+            ${{ steps.deploy.outputs.pages-deployment-alias-url }}

.gitignore

@@ -4,10 +4,10 @@ backend/config.yml
 backend/config.yaml
 .ravnar_local
 
-# Docs (Docusaurus)
+# Docs (Astro)
 docs/node_modules/
-docs/build/
-docs/.docusaurus/
+docs/dist/
+docs/.astro/
 docs/.cache-loader/
 
 # Local agent / contributor playbook (not for the public repo)

docs/README.md

@@ -1,11 +1,11 @@
 # Nebari Chat Pack Documentation
 
-This directory contains the [Docusaurus](https://docusaurus.io/) site for the Nebari Chat pack. The site is written in TypeScript.
+This directory contains the [Astro](https://astro.build) + [Starlight](https://starlight.astro.build) site for the Nebari Chat Pack.
 
 ## Prerequisites
 
-- Node.js `>= 20` (enforced by the `engines` field in `package.json`).
-- npm (bundled with Node.js).
+- Node.js `>= 22` (enforced by the `engines` field in `package.json`)
+- npm (bundled with Node.js)
 
 ## Install
 
@@ -17,33 +17,53 @@ npm install
 ## Local development
 
 ```bash
-npm start
+npm run dev
 ```
 
-Starts the Docusaurus dev server with hot reload on http://localhost:3000/.
+Starts the Astro dev server with hot reload on http://localhost:4321/.
 
 ## Production build
 
 ```bash
 npm run build
 ```
 
-Emits static files to `docs/build/`. The search index is generated as part of the production build.
+Emits static files to `docs/dist/`.
 
 ## Preview the production build
 
 ```bash
-npm run serve
+npm run preview
 ```
 
-Serves the contents of `docs/build/` locally so you can verify the production output, including search.
+Serves the contents of `docs/dist/` locally so you can verify the production output.
+
+## Unit tests
+
+```bash
+npm test
+```
+
+Runs the Vitest suite (currently: the `remark-base-links` plugin tests).
 
 ## Type checking
 
 ```bash
 npm run typecheck
 ```
 
+## Link checking
+
+```bash
+bash ../scripts/check-links.sh
+```
+
+To test with the production base path: `BASE=/chat-pack/ bash ../scripts/check-links.sh`
+
+## Content
+
+Pages live in `src/content/docs/`. Each `.md` or `.mdx` file becomes a page. The sidebar is configured in `astro.config.mjs` under `starlight.sidebar`.
+
 ## CI
 
-The [`Docs` workflow](../.github/workflows/docs.yml) builds the site for every pull request and push to `main` that touches `docs/`.
+The [`Docs` workflow](../.github/workflows/docs.yml) runs unit tests, builds the site, checks internal links, and deploys to [Cloudflare Pages](https://pages.cloudflare.com) on every push to `main` and every pull request that touches `docs/`. Pull requests get a preview URL posted as a comment; the [`Docs preview cleanup`](../.github/workflows/docs-preview-cleanup.yml) workflow removes it when the PR closes.

docs/astro.config.mjs

@@ -0,0 +1,28 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import { nebari } from '@nebari/starlight';
+import rehypeMermaid from 'rehype-mermaid';
+import remarkBaseLinks from './src/plugins/remark-base-links';
+
+export default defineConfig({
+  base: process.env.BASE || '/',
+  site: process.env.SITE,
+  integrations: [
+    starlight({
+      title: 'Nebari Chat Pack',
+      description: 'Deploy a chat interface on Nebari.',
+      // Shared Nebari identity (brand colors, fonts, logo, favicon, footer, and
+      // GitHub social link) comes from the @nebari/starlight theme plugin. On the
+      // portal the header logo returns users to the pack catalog.
+      plugins: [nebari({ logoHref: 'https://packs.nebari.dev/' })],
+      sidebar: [
+        { label: 'Introduction', slug: 'index' },
+      ],
+    }),
+  ],
+  markdown: {
+    syntaxHighlight: { type: 'shiki', excludeLangs: ['mermaid'] },
+    remarkPlugins: [[remarkBaseLinks, { base: process.env.BASE || '/' }]],
+    rehypePlugins: [[rehypeMermaid, { strategy: 'inline-svg' }]],
+  },
+});