[Docs] Replace the Docusaurus site with Astro + Starlight

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

@@ -0,0 +1,35 @@
+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: rayserve-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,56 +1,86 @@
 name: Docs
-
 on:
   push:
     branches: [main]
-    paths:
-      - 'docs/**'
+    paths: ['docs/**', 'scripts/check-links.sh', '.github/workflows/docs.yml']
   pull_request:
-    paths:
-      - 'docs/**'
-
+    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: rayserve-pack
 jobs:
-  build:
-    name: Build
+  docs:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with: { fetch-depth: 0 }
 
-      - name: Set up Node.js
-        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: '20'
-          cache: 'npm'
+          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: Unit tests
         working-directory: docs
+        run: npm test
+
+      - 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
-        run: npm run build
         working-directory: docs
+        env:
+          SITE: ${{ steps.base.outputs.site }}
+          BASE: ${{ steps.base.outputs.base }}
+        run: npm run build
 
-      - name: Upload build artifact
-        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
+      - name: Check internal links
+        env:
+          BASE: ${{ steps.base.outputs.base }}
+        run: SKIP_BUILD=1 bash scripts/check-links.sh
+
+      - 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@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
+          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

@@ -5,11 +5,13 @@ chart/Chart.lock
 # Dev environment
 dev/.cache/
 
-# Docs (Docusaurus)
+# Docs (Astro)
 docs/node_modules/
-docs/build/
-docs/.docusaurus/
-docs/.cache-loader/
+docs/dist/
+docs/.astro/
+docs/npm-debug.log*
+docs/.env
+docs/.env.production
 
 # Local agent / contributor playbook (not for the public repo)
 AGENT.md

README.md

@@ -329,8 +329,29 @@ nebari-rayserve-pack/
       NOTES.txt                # Post-install usage instructions
   dev/
     Makefile                   # Local dev with full Nebari stack on kind
+  docs/                        # Astro + Starlight documentation site
 ```
 
+## Documentation
+
+The docs site lives in [`docs/`](docs/) and is built with [Astro](https://astro.build) +
+[Starlight](https://starlight.astro.build) using the shared `@nebari/starlight` theme. It
+deploys to [packs.nebari.dev/rayserve-pack/](https://packs.nebari.dev/rayserve-pack/) on
+every merge to `main`; pull requests that touch `docs/` get a preview URL posted as a
+comment.
+
+```bash
+cd docs
+npm ci
+npm run dev     # dev server with hot reload at http://localhost:4321
+npm run build   # static build into docs/dist/
+npm test        # unit tests
+```
+
+Pages live in `docs/src/content/docs/` - each `.md` or `.mdx` file becomes a page, and the
+sidebar is configured in `docs/astro.config.mjs`. See [`docs/README.md`](docs/README.md) for
+details.
+
 ## Troubleshooting
 
 ### Ray Dashboard returns 500 via NebariApp

docs/README.md

@@ -1,49 +1,63 @@
-# Nebari Ray Serve Pack Documentation
+# Nebari Rayserve Pack Documentation
 
-This directory contains the [Docusaurus](https://docusaurus.io/) site for the Nebari Ray Serve pack. The site is written in TypeScript.
+This directory contains the [Astro](https://astro.build) + [Starlight](https://starlight.astro.build) site for the Nebari Rayserve 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
 
 ```bash
 cd docs
-npm install
+npm ci
 ```
 
 ## 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.
 
-## Type checking
+## Unit tests
 
 ```bash
-npm run typecheck
+npm test
 ```
 
+Runs the Vitest suite (currently: the `remark-base-links` plugin tests).
+
+## Link checking
+
+```bash
+bash ../scripts/check-links.sh
+```
+
+To test with the production base path: `BASE=/rayserve-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,42 @@
+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';
+
+// Deploy conventions, set by .github/workflows/docs.yml (PACK_SLUG: rayserve-pack):
+//
+//   main    SITE=https://packs.nebari.dev              BASE=/rayserve-pack/
+//   preview SITE=https://<branch>.rayserve-pack.pages.dev  BASE=/
+//
+// The `site` default mirrors the production origin so a plain `npm run build`
+// still emits correct canonical URLs and a sitemap. `base` stays `/` by default
+// so the dev server and local previews serve from the root.
+const SITE = process.env.SITE || 'https://packs.nebari.dev';
+const BASE = process.env.BASE || '/';
+
+export default defineConfig({
+  base: BASE,
+  site: SITE,
+  integrations: [
+    starlight({
+      title: 'Nebari Rayserve Pack',
+      description: 'Scalable model serving with Ray Serve through the RayService CRD, with optional routing, TLS, and OIDC via the nebari-operator.',
+      // 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: 'Getting Started',
+          items: [{ label: 'Introduction', link: '/' }],
+        },
+      ],
+    }),
+  ],
+  markdown: {
+    syntaxHighlight: { type: 'shiki', excludeLangs: ['mermaid'] },
+    remarkPlugins: [[remarkBaseLinks, { base: BASE }]],
+    rehypePlugins: [[rehypeMermaid, { strategy: 'inline-svg' }]],
+  },
+});