[Docs] Replace the Docusaurus site with Astro + Starlight

[jbouder]

Reference Issues or PRs

Closes #21. Replaces #26 — 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

The state on main

main is mid-migration and the docs job cannot succeed as-is:

• docs/package.json declares Astro + Starlight, but the site next to it is still Docusaurus (docusaurus.config.ts, sidebars.ts, docs/docs/, src/css/custom.css) and there is no astro.config.mjs, no src/content.config.ts, and no content collection.
• .github/workflows/docs.yml was copied from superset-pack and still sets PACK_SLUG: superset-pack, so a successful build would deploy this pack's docs over Superset's Pages project.
• scripts/check-links.sh is referenced by the workflow but does not exist.
• There is no docs-preview-cleanup.yml, so PR previews would never be reaped.

This PR finishes the migration. 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.yml corrected to PACK_SLUG: rayserve-pack, plus the missing Docs preview cleanup workflow. main builds at BASE=/rayserve-pack/ and publishes to packs.nebari.dev/rayserve-pack/; PRs build at BASE=/ and get a preview URL posted as a comment.
• 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. 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=/rayserve-pack/ npm run build && SKIP_BUILD=1 BASE=/rayserve-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 rayserve-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).

🤖 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/rayserve-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 rayserve-pack exactly.

• docs_site: true
• links.docs: https://packs.nebari.dev/rayserve-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.rayserve-pack.pages.dev