Astro docs migration

.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: mlflow-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

@@ -0,0 +1,86 @@
+name: Docs
+on:
+  push:
+    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: mlflow-pack
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - 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
+        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: 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@v3
+        with:
+          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@v3
+        with:
+          comment-tag: docs-preview
+          message: |
+            📄 **Docs preview** for `${{ github.event.pull_request.head.ref }}`:
+            ${{ steps.deploy.outputs.pages-deployment-alias-url }}

.gitignore

@@ -29,6 +29,5 @@ Thumbs.db
 CLAUDE.md
 
 node_modules/
-build/
-.docusaurus/
-.cache-loader/
+docs/dist/
+docs/.astro/

docs/README.md

@@ -1,49 +1,63 @@
 # Nebari MLflow Pack Documentation
 
-This directory contains the [Docusaurus](https://docusaurus.io/) site for the Nebari MLflow Pack. The site is written in TypeScript.
+This directory contains the [Astro](https://astro.build) + [Starlight](https://starlight.astro.build) site for the Nebari MLflow 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 covers the `remark-base-links` plugin).
+
+## Link checking
+
+```bash
+bash ../scripts/check-links.sh
+```
+
+Builds the site and verifies every internal link/image resolves to a real file under `docs/dist/`. To check with the production base path: `BASE=/mlflow-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 [`Deploy docs to GitHub Pages` workflow](../.github/workflows/deploy-docs.yml) builds the site for every pull request and push to `main`.
+The [`Docs` workflow](../.github/workflows/docs.yml) builds, tests, and link-checks the site on every pull request and push to `main`, and deploys it to [Cloudflare Pages](https://pages.cloudflare.com). Pull requests get a preview URL posted as a comment.

docs/astro.config.mjs

@@ -0,0 +1,53 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import react from '@astrojs/react';
+import tailwindcss from '@tailwindcss/vite';
+import rehypeMermaid from 'rehype-mermaid';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import remarkBaseLinks from './src/plugins/remark-base-links';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  base: process.env.BASE || '/',
+  site: process.env.SITE,
+  integrations: [
+    react(),
+    starlight({
+      title: 'Nebari MLflow Pack',
+      description: 'Deploy MLflow on Nebari with Keycloak authentication, PostgreSQL, and TLS.',
+      logo: {
+        light: './src/assets/logo.svg',
+        dark: './src/assets/logo-dark.svg',
+        replacesTitle: false,
+      },
+      customCss: [
+        '@fontsource-variable/geist',
+        '@fontsource/ibm-plex-mono',
+        './src/styles/tailwind.css',
+      ],
+      components: {
+        SocialIcons: './src/components/SocialIcons.astro',
+      },
+      sidebar: [
+        { label: 'Introduction', slug: 'index' },
+        { label: 'Authentication Flow', slug: 'auth-flow' },
+        { label: 'NebariApp CRD Reference', slug: 'nebariapp-crd-reference' },
+      ],
+    }),
+  ],
+  markdown: {
+    syntaxHighlight: { type: 'shiki', excludeLangs: ['mermaid'] },
+    remarkPlugins: [[remarkBaseLinks, { base: process.env.BASE || '/' }]],
+    rehypePlugins: [[rehypeMermaid, { strategy: 'inline-svg' }]],
+  },
+  vite: {
+    plugins: [tailwindcss()],
+    resolve: {
+      alias: {
+        '@': path.resolve(__dirname, './src'),
+      },
+    },
+  },
+});

docs/components.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-vega",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles/nebari-tokens.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "utils": "@/lib/utils",
+    "hooks": "@/hooks"
+  },
+  "registries": {
+    "@nebari": "https://nebari-dev.github.io/nebari-design/r/{name}.json"
+  }
+}