Add base Astro + Nebari Starlight docs site (experimental)

.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: pi-coding-agent-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,78 @@
+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: pi-coding-agent-pack
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with: { fetch-depth: 0 }
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install deps
+        working-directory: docs
+        run: npm ci
+
+      - 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@ebbaa1584979971c8614a24965b4405ff95890e0 # v4.0.0
+        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@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 }}

README.md

@@ -104,6 +104,18 @@ Then set your Helm values to the pushed image tag/digest:
 - `pi.image.tag`
 - `jupyterhub.custom.pi-image` (prefer digest pin)
 
+## Documentation
+
+An experimental [Astro](https://astro.build) + [Starlight](https://starlight.astro.build) docs site lives in [`docs/`](docs/) (content coming soon). Run it locally with:
+
+```bash
+cd docs
+npm ci
+npm run dev
+```
+
+See [`docs/README.md`](docs/README.md) for details.
+
 ## Notes
 
 - Legacy PVC-based shared-skills sync is removed from runtime flow.

docs/.gitignore

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

docs/README.md

@@ -0,0 +1,66 @@
+# Pi Coding Agent Pack Documentation
+
+This directory contains the [Astro](https://astro.build) + [Starlight](https://starlight.astro.build) site for the Pi Coding Agent Pack.
+
+> **Experimental** — this site is a scaffold. Content is coming soon; the
+> landing page is a placeholder.
+
+## Prerequisites
+
+- Node.js `>= 22` (enforced by the `engines` field in `package.json`)
+- npm (bundled with Node.js)
+
+## Install
+
+```bash
+cd docs
+npm ci
+```
+
+## Local development
+
+```bash
+npm run dev
+```
+
+Starts the Astro dev server with hot reload on http://localhost:4321/.
+
+## Production build
+
+```bash
+npm run build
+```
+
+Emits static files to `docs/dist/`.
+
+## Preview the production build
+
+```bash
+npm run preview
+```
+
+Serves the contents of `docs/dist/` locally so you can verify the production output.
+
+## 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`.
+
+## Link checking
+
+```bash
+bash ../scripts/check-links.sh
+```
+
+To test with the production base path: `BASE=/pi-coding-agent-pack/ bash ../scripts/check-links.sh`
+
+## Deploy conventions
+
+`astro.config.mjs` reads two environment variables so the same build works
+locally, on preview deployments, and on the packs portal:
+
+- `SITE` — canonical origin (defaults to `https://packs.nebari.dev`)
+- `BASE` — base path (defaults to `/`; the portal serves this pack at `/pi-coding-agent-pack/`)
+
+## CI
+
+The [`Docs` workflow](../.github/workflows/docs.yml) 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. Deploys require the `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` repository secrets.

docs/astro.config.mjs

@@ -0,0 +1,45 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import { nebari } from '@nebari/starlight';
+import remarkBaseLinks from './src/plugins/remark-base-links';
+
+// Deploy conventions (PACK_SLUG: pi-coding-agent-pack):
+//
+//   main    SITE=https://packs.nebari.dev                       BASE=/pi-coding-agent-pack/
+//   preview SITE=https://<branch>.pi-coding-agent-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: 'Pi Coding Agent Pack',
+      description:
+        'Extends Nebari’s JupyterHub stack with a Pi coding-agent workflow: launcher service, named-server profiles, and a browser terminal.',
+      // 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/' })],
+      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/pi-coding-agent-pack/edit/main/docs/',
+      },
+      sidebar: [
+        {
+          label: 'Getting Started',
+          items: [{ label: 'Introduction', link: '/' }],
+        },
+      ],
+    }),
+  ],
+  markdown: {
+    remarkPlugins: [[remarkBaseLinks, { base: BASE }]],
+  },
+});