Migrate Documentation from Docusaurus to Astro + Starlight with the Nebari Theme

[jbouder]

Summary

Migrate the Nebari documentation site (docs/) from Docusaurus 3 to Astro + Starlight, themed with the shared @nebari/starlight plugin. This follows the same migration pattern already completed for jhub-apps in nebari-dev/jhub-apps#719, and covers all three doc collections (docs/docs, docs/classic, docs/community, ~110 markdown/MDX files), the blog, static assets, and the Netlify build/redirect configuration.

Motivation

• Aligns the Nebari docs with the shared @nebari/starlight theme so all nebari-dev doc sites (jhub-apps, and future packs) have consistent branding maintained in one place
• Astro + Starlight is significantly lighter and faster to build than the current Docusaurus 3 stack (no React runtime shipped for static content)
• Removes a large custom dependency surface (docusaurus-lunr-search, docusaurus-plugin-sass, Babel, ESLint config, swizzled components) in favor of Starlight built-ins (search via Pagefind, sidebar, dark mode, edit links)
• The jhub-apps migration branch (719-astro-starlight-migration) provides proven patterns to reuse: astro.config.mjs with the nebari() plugin, a custom Head.astro for Google Analytics + vanilla-cookieconsent, and a Bun-based build smoke test that verifies every page, sidebar link, and internal href/image resolves

Acceptance Criteria

• New Astro project replaces the Docusaurus app in docs/ with @astrojs/starlight, @nebari/starlight, and astro as the core dependencies
• astro.config.mjs uses the nebari({ logoHref, githubHref }) Starlight plugin, sets site: 'https://www.nebari.dev', and configures editLink.baseUrl to point at this repo
• All content from docs/docs, docs/classic, and docs/community is migrated into src/content/docs/ with MDX components (admonitions, tabs, MarkdownTable, PlannedProvider) converted to Starlight/Astro equivalents
• Sidebar structure in astro.config.mjs reproduces the current sidebars.js, sidebarsClassic.js, and sidebarsCommunity.js navigation
• Existing URLs keep working: current netlify.toml redirects (including /docs/* → /classic/*) are preserved or replaced by equivalent Astro/Netlify redirects, with no broken inbound links
• Custom Head.astro component carries over Google Analytics and the vanilla-cookieconsent banner
• Search works on the built site (Starlight's built-in Pagefind replaces docusaurus-lunr-search)
• Mermaid diagrams in migrated pages render correctly (replacement for @docusaurus/theme-mermaid)
• Build smoke tests (modeled on jhub-apps docs/test/build.test.ts) verify every page renders with its title and every internal href/image resolves; they run in CI
• netlify.toml build settings updated (command, publish directory) and a Netlify deploy preview builds green
• docs/README.md and CONTRIBUTING.md updated with the new local dev workflow (bun install, bun run dev, bun run build, bun test)
• Docusaurus dependencies, babel.config.js, sidebars*.js, swizzled components, and related config removed

Out of Scope

• Changes to the @nebari/starlight theme itself — theme fixes go to nebari-dev/starlight
• Rewriting or restructuring doc content beyond what the format conversion requires (content edits are separate issues)
• Migrating the blog to a new format beyond a working equivalent (only 2 posts exist; a follow-up can redesign it)
• Docs versioning — the current site is unversioned and stays that way

[jbouder]

Currently blocked. Prioritizing adding and updating existing documentation first.