Work item to migrate our existing mkdocs site to Astro Starlight/Astro.

At the end of this task, the docs site should be runnable on Starlight/Astro using the existing markdown docs.

On a branch (new_docs), create an astro/starlight project (via NPM) that renders all pages that currently exist in mkdocs today. For page titles and navigation, read from the mkdocs.yml file.

Implementation Requirements

Based on clarification discussion and repository analysis.

Technical Approach

• Target Framework: Astro with Starlight documentation theme
• Branch: new_docs
• Coexistence: Keep both Astro and MkDocs configurations side-by-side (migration/removal of MkDocs will be done later)
• Navigation Source: Parse mkdocs.yml programmatically to generate Starlight sidebar configuration

Project Setup

• Initialize Starlight project via npm create astro@latest -- --template starlight
• Configure to coexist with existing MkDocs setup
• Set up build scripts to parse mkdocs.yml for navigation

Content Migration

• All 135 existing markdown docs render correctly
• Preserve existing directory structure under docs/
• Assets (images, logos) accessible and rendering

Mermaid Diagrams

• Install and configure starlight-mermaid plugin or equivalent
• Verify mermaid code blocks render correctly (20+ files use mermaid)
• Test diagrams in: user-guide/quickstart/, examples/python/, user-guide/concepts/

Tabbed Content

• Migrate === "Python" / === "TypeScript" syntax to Starlight <Tabs> component
• Ensure code tabs display correctly throughout docs

Custom Macros (if feasible)

• Create Astro/MDX equivalents for ts_not_supported() macro
• Create Astro/MDX equivalents for ts_not_supported_code() macro
• Keep syntax compatible with current usage for merge simplicity

Snippet Includes

• Implement alternative for --8<-- snippet markers used in TypeScript examples
• Ensure external code file inclusion works for .ts files

Error Page

• Use Starlight's default 404 page (no custom implementation needed)

Out of Scope (Deferred to Follow-up Tasks)

• ❌ API documentation generation (Python/TypeScript)
• ❌ Search exclusion configuration (depends on API docs)
• ❌ Mike versioning / version selector
• ❌ Removal of MkDocs configuration

Acceptance Criteria

• Existing docs render using default Starlight theme
• Mermaid diagrams render correctly
• Error page renders successfully (default 404)
• Navigation structure matches current mkdocs.yml hierarchy
• Site runs locally with npm run dev
• Both Astro and MkDocs can coexist in the repository

Files to Create/Modify

New Files (Starlight Project)

• astro.config.mjs - Astro configuration
• src/content/config.ts - Content collection config
• src/content/docs/ - Symlink or reference to existing docs/
• package.json updates for Astro dependencies
• Navigation generation script (parse mkdocs.yml)

Existing Files to Preserve

• mkdocs.yml - Keep as-is
• docs/**/*.md - No modifications needed
• docs/assets/ - Keep as-is
• macros.py - Keep for MkDocs compatibility

Reference Information

Current MkDocs Features Used

Useful Resources

• Starlight Getting Started
• Starlight Sidebar Config
• Starlight Components