Add "Building a software pack" docs site and portal convention

.github/workflows/docs.yml

@@ -0,0 +1,67 @@
+name: Docs
+on:
+  push:
+    branches: [main]
+    paths: ['docs/site/**', '.github/workflows/docs.yml']
+  pull_request:
+    paths: ['docs/site/**', '.github/workflows/docs.yml']
+  workflow_dispatch:
+permissions:
+  contents: read
+  pull-requests: write
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+env:
+  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: 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 }
+
+      - name: Compute baseURL and deploy branch
+        id: base
+        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 "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"
+          fi
+
+      - name: Build
+        run: cd docs/site && hugo --gc --minify --baseURL "${{ steps.base.outputs.url }}"
+
+      # Fork PRs cannot read secrets; skip deploy there (build above still gates).
+      - 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/site/public --project-name=${{ env.CF_PROJECT }} --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

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

README.md

@@ -848,6 +848,54 @@ helm version
 helm dependency update examples/wrap-existing-chart/chart/
 ```
 
+## Documentation Portal
+
+Pack docs are served at `packs.nebari.dev/<repo-short-name>/`. The portal routes each
+pack's docs site transparently via a Cloudflare edge Worker so users see a single
+unified domain, while each pack deploys and previews independently.
+
+### Opting in
+
+1. **Add `docs_site: true` to `pack-metadata.yaml`:**
+
+   ```yaml
+   docs_site: true
+   links:
+     docs: https://packs.nebari.dev/<your-repo-name>/
+   ```
+
+2. **Copy `.github/workflows/docs.yml` from this repo** into your pack repo and
+   update two values:
+
+   | Variable | Set to |
+   |----------|--------|
+   | `PACK_SLUG` (env) | your repo's short name (the segment after `nebari-dev/`) |
+   | `--project-name=...` in the `wrangler` command | the matching Cloudflare Pages project name |
+
+   For most packs, `PACK_SLUG` and the project name are the same (e.g., `llm-serving-pack`).
+   The template repo is a special case: `PACK_SLUG: building-a-software-pack` routes to
+   `packs.nebari.dev/building-a-software-pack/` but deploys to the `nebari-software-pack-template`
+   CF Pages project.
+
+3. **Add your pack to `tracked-packs.yaml`** in
+   [software-pack-dashboard](https://github.com/nebari-dev/software-pack-dashboard) if it is
+   not already there. The dashboard schema is at
+   `nebari-dev/software-pack-dashboard/schema/pack-metadata.schema.json`.
+
+### How it works
+
+- **Production:** push to `main` builds Hugo with `baseURL https://packs.nebari.dev/<slug>/`
+  and deploys to the pack's Cloudflare Pages project.
+- **PR previews:** every pull request builds with `baseURL https://<alias>.<slug>.pages.dev/`
+  and deploys to a preview deployment; a bot comments the preview URL on the PR.
+- **Fork PRs:** the build and link-check run, but the deploy step is skipped (fork PRs
+  cannot read org secrets).
+
+The edge Worker at `packs.nebari.dev` proxies `/<slug>/*` to `<slug>.pages.dev/*`
+transparently. For packs in `tracked-packs.yaml` with `docs_site: true`, the route is
+generated automatically. The `building-a-software-pack` route for this template repo is
+wired in the dashboard's static extra-routes map.
+
 ## License
 
 Apache 2.0 - see [LICENSE](LICENSE).

docs/site/content/_index.md

@@ -0,0 +1,22 @@
++++
+title = "Building a Software Pack"
++++
+
+This guide covers Nebari Software Packs: what they are, how to build one, and how to maintain it.
+
+A software pack is a Kubernetes application bundled with a `NebariApp` custom resource. When you deploy one, the Nebari platform automatically wires it into the shared routing, TLS, and OIDC authentication systems - no manual gateway or certificate configuration required.
+
+## In this guide
+
+- **[What is a software pack](/what-is-a-software-pack/)** - definition, why packs exist, pack contents, the NebariApp resource, pack lifecycle, and official vs community packs
+- **[Build your own](/build-your-own/)** - start from the template, choose an example, deploy via ArgoCD, private and organizational packs
+
+## Reference pages
+
+- **[NebariApp CRD reference](/nebariapp-crd-reference/)** - complete field-by-field reference for the `NebariApp` custom resource
+- **[Authentication flow](/auth-flow/)** - how OIDC works end-to-end; reading the IdToken in your app
+- **[Release readiness](/release-readiness/)** - maturity levels and the promotion checklist for first-party packs
+
+## Pack template
+
+Use the [nebari-software-pack-template](https://github.com/nebari-dev/nebari-software-pack-template) as your starting point. It includes five examples spanning plain YAML, Kustomize, basic Helm, auth-aware apps, and wrapping an existing upstream chart.