[Docs] Scaffold the Astro + Starlight docs site

[jbouder]

Reference Issues or PRs

Closes #2. Replaces #3 — 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

This repo had no docs site — just two loose markdown files under docs/. Scope is scaffolding only — no new content is written.

• 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, so there is no hand-maintained CSS token copy to drift
• 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. main builds at BASE=/langfuse-pack/ and publishes to packs.nebari.dev/langfuse-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 for the Astro build artifacts

Content carried over

docs/configuration.md and docs/release-readiness.md move into docs/src/content/docs/ so they become pages on the site. Their bodies are unchanged apart from added title/description frontmatter and dropping the duplicate leading # H1, since Starlight renders the frontmatter title as the page heading. README references to the old paths now point at the published pages.

This repo has no Makefile, so the docs commands are documented as plain npm invocations (same as longhorn-backup-pack and mlflow-pack). Happy to add one if that's preferred.

Testing

Locally, from a clean checkout:

npm ci        # 513 packages
npm test      # 10 passed
npm run build # 4 pages built
SKIP_BUILD=1 bash scripts/check-links.sh                                     # LINKS_OK
BASE=/langfuse-pack/ npm run build && SKIP_BUILD=1 BASE=/langfuse-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 langfuse-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/langfuse-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 langfuse-pack exactly.

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