[Docs] Replace the Docusaurus site with Astro + Starlight

[jbouder]

Reference Issues or PRs

Closes #11. Replaces #12 — same goal, rebased on current main and aligned with the docs setup the other packs have since converged on (nebi-pack, apps-pack, nebari-chat-pack).

What does this implement/fix?

• Documentation Update

Migrates the docs site off Docusaurus 3 + yarn + GitHub Pages. Scope is scaffolding only — the existing Introduction page carries over as-is; real content lands separately.

• Astro + Starlight static site in docs/, npm for dependency management (Node >= 22)
• @nebari/starlight shared theme plugin supplies the Nebari identity — brand colors, fonts, logo, favicon, footer, GitHub link — built on the nebari design system. This replaces docs/src/css/custom.css, a hand-copied snapshot of the design tokens that had to be re-synced by hand.
• remark-base-links plugin so root-absolute markdown links survive the production subpath base, with vitest coverage (10 tests)
• scripts/check-links.sh verifies every internal link in dist/ resolves
• Docs workflow: unit tests → build → internal link check → deploy to Cloudflare Pages, replacing deploy-docs.yml (GitHub Pages). main builds at BASE=/superset-pack/ and publishes to packs.nebari.dev/superset-pack/; PRs build at BASE=/ and get a preview URL posted as a comment. A Docs preview cleanup workflow deletes the preview when the PR closes.
• docs/README.md and a README section on running and updating the docs; .gitignore entries swapped from the Docusaurus artifacts to the Astro ones

The only Makefile in this repo is dev/Makefile, which drives the kind dev cluster — docs targets would be out of place there, so the docs commands are documented as plain npm invocations (same as longhorn-backup-pack and mlflow-pack). Happy to add a root Makefile instead if that's preferred.

Testing

Locally, from a clean checkout:

npm ci        # 513 packages
npm test      # 10 passed
npm run build # 2 pages built
SKIP_BUILD=1 bash scripts/check-links.sh                                     # LINKS_OK
BASE=/superset-pack/ npm run build && SKIP_BUILD=1 BASE=/superset-pack/ ...  # LINKS_OK

Both the root base (PR previews) and the production subpath base build and link-check clean.

Before merging

The Cloudflare Pages project superset-pack and the CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID repo secrets need to exist, otherwise the deploy step fails (test, build, and link check still gate the PR). The old GitHub Pages site can be retired once this lands.

🤖 Generated with Claude Code

[jbouder]

Added a second commit registering the docs site in pack-metadata.yaml.

This turned out to be load-bearing, not cosmetic. software-pack-dashboard/generate_routes.py builds the portal route table by reading each tracked pack's pack-metadata.yaml and emitting <slug> -> https://<slug>.pages.dev only for packs with docs_site: true, where slug is repo.split("/")[-1]. Without it, packs.nebari.dev/superset-pack/ keeps falling through to the dashboard even after the Pages project exists and the site deploys. That same code path is why the Cloudflare Pages project has to be named superset-pack exactly.

• docs_site: true
• links.docs: https://packs.nebari.dev/superset-pack/
• The Starlight site description and landing-page frontmatter now match this repo's GitHub description, which is what the dashboard's Description column actually reads — so the two can't drift. No description: field was added to the metadata, since the template notes the dashboard doesn't source it from there.

Validated against schema/pack-metadata.schema.json; npm test, the production-base build, and the link check all still pass.

[github-actions]

📄 Docs preview for docs/astro-starlight-scaffold:
https://docs-astro-starlight-scaffol.superset-pack.pages.dev