Migrate the guide site from Hugo to Astro + Starlight

.github/workflows/docs.yml

@@ -13,39 +13,40 @@ concurrency:
   group: docs-${{ github.ref }}
   cancel-in-progress: true
 env:
+  # Route slug on the portal; also the production Astro base path (/building-a-software-pack/).
   PACK_SLUG: building-a-software-pack
-  # CF project name differs from the route slug for the template guide; the preview
-  # hostname and the deploy target must use the project, not the slug.
+  # CF project name differs from the route slug for the template guide.
   CF_PROJECT: nebari-software-pack-template
 jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
-      - uses: actions/setup-go@v5
-        with: { go-version-file: docs/site/go.mod, cache: false }
-      - uses: peaceiris/actions-hugo@v3
-        with: { hugo-version: "0.159.0", extended: true }
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
 
-      - name: Compute baseURL and deploy branch
-        id: base
+      - name: Compute base path and deploy branch
+        id: cf
         env:
           GH_REF: ${{ github.ref }}
           GH_HEAD_REF: ${{ github.head_ref || github.ref_name }}
         run: |
           if [ "$GH_REF" = "refs/heads/main" ]; then
-            echo "url=https://packs.nebari.dev/${PACK_SLUG}/" >> "$GITHUB_OUTPUT"
+            echo "base_path=/${PACK_SLUG}/" >> "$GITHUB_OUTPUT"
             echo "branch=main" >> "$GITHUB_OUTPUT"
           else
-            HEAD="$GH_HEAD_REF"
-            ALIAS=$(printf '%s' "$HEAD" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g')
-            echo "url=https://${ALIAS}.${CF_PROJECT}.pages.dev/" >> "$GITHUB_OUTPUT"
-            echo "branch=${HEAD}" >> "$GITHUB_OUTPUT"
+            # PR previews serve at the pages.dev alias root (no Worker), so build at root base.
+            echo "base_path=/" >> "$GITHUB_OUTPUT"
+            echo "branch=${GH_HEAD_REF}" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Install
+        run: cd docs/site && bun install --frozen-lockfile
+
       - name: Build
-        run: cd docs/site && hugo --gc --minify --baseURL "${{ steps.base.outputs.url }}"
+        # Dynamic base: subpath on main, root on PR previews (astro.config reads BASE_PATH).
+        run: cd docs/site && BASE_PATH="${{ steps.cf.outputs.base_path }}" bun run build
 
       # Fork PRs cannot read secrets; skip deploy there (build above still gates).
       - name: Deploy to Cloudflare Pages
@@ -55,7 +56,7 @@ jobs:
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          command: pages deploy docs/site/public --project-name=${{ env.CF_PROJECT }} --branch=${{ steps.base.outputs.branch }}
+          command: pages deploy docs/site/dist --project-name=${{ env.CF_PROJECT }} --branch=${{ steps.cf.outputs.branch }}
 
       - name: Comment preview URL
         if: ${{ github.event_name == 'pull_request' && steps.deploy.outcome == 'success' }}

.gitignore

@@ -25,9 +25,5 @@ venv/
 .DS_Store
 Thumbs.db
 
-# Hugo build output
-docs/site/public/
-docs/site/.hugo_build.lock
-
 # Claude
 CLAUDE.md

docs/site/.gitignore

@@ -0,0 +1,3 @@
+dist/
+.astro/
+node_modules/

docs/site/astro.config.mjs

@@ -0,0 +1,52 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import { nebari } from '@nebari/starlight';
+import { rehypeBaseLinks } from './src/rehype-base-links.mjs';
+
+// Dynamic base. Production (main) uses the subpath: the portal Worker strips
+// /building-a-software-pack/ before proxying to this Pages project, so files are served
+// from its root. PR previews build with BASE_PATH=/ because they are served at
+// <alias>.pages.dev/ directly (no Worker). Astro emits files at dist/ root either way;
+// base only prefixes link/asset URLs. Default is the production subpath so local
+// builds and tests match production.
+const base = process.env.BASE_PATH ?? '/building-a-software-pack/';
+
+export default defineConfig({
+  site: 'https://packs.nebari.dev',
+  base,
+  // Astro does not prefix `base` onto root-absolute links written in Markdown body
+  // content, so this rehype pass does it for internal links and images.
+  markdown: { rehypePlugins: [[rehypeBaseLinks, { base }]] },
+  integrations: [
+    starlight({
+      title: 'Building a Software Pack',
+      description:
+        'A deep-dive guide to building, deploying, and maintaining Nebari Software Packs - Kubernetes applications with routing, TLS, and OIDC wired in.',
+      plugins: [nebari({ logoHref: 'https://packs.nebari.dev/' })],
+      editLink: {
+        // Starlight appends the source path (src/content/docs/<file>.md) to this base,
+        // so it must point at the Astro project root inside the repo.
+        baseUrl: 'https://github.com/nebari-dev/nebari-software-pack-template/edit/main/docs/site/',
+      },
+      sidebar: [
+        {
+          label: 'Getting Started',
+          items: [
+            { label: 'Introduction', link: '/' },
+            { label: 'What is a software pack', link: '/what-is-a-software-pack/' },
+            { label: 'Concepts', link: '/concepts/' },
+            { label: 'Build your own', link: '/build-your-own/' },
+          ],
+        },
+        {
+          label: 'Reference',
+          items: [
+            { label: 'NebariApp CRD', link: '/nebariapp-crd-reference/' },
+            { label: 'Authentication Flow', link: '/auth-flow/' },
+            { label: 'Release Readiness', link: '/release-readiness/' },
+          ],
+        },
+      ],
+    }),
+  ],
+});