Migrate to new CMS running in development using default theme #442

[zastrowm]

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

Feature	MkDocs Implementation	Starlight Equivalent
Navigation	nav: in mkdocs.yml	Sidebar config / autogenerate
Mermaid	pymdownx.superfences	starlight-mermaid plugin
Tabs	pymdownx.tabbed	<Tabs> component
Admonitions	admonition extension	<Aside> component
Code highlighting	codehilite	Built-in
Snippets	pymdownx.snippets	Custom component needed

Useful Resources

• Starlight Getting Started
• Starlight Sidebar Config
• Starlight Components

[zastrowm]

/strands

[github-actions]

📋 Repository Analysis & Clarifying Questions

I've analyzed the repository structure and the Starlight/Astro framework. Here's what I found and some questions to ensure a smooth migration.

Repository Analysis

Current Setup

• Doc Framework: MkDocs with Material theme
• Total Markdown Files: 135 documentation pages
• Navigation: Complex hierarchical structure defined in mkdocs.yml

Key Components That Need Migration

Component	Current Implementation	Migration Notes
Navigation	mkdocs.yml nav section	Will parse and recreate in Starlight sidebar config
Mermaid Diagrams	~20+ files with mermaid code blocks	Starlight has starlight-mermaid plugin
Python/TS Tabs	=== "Python" / === "TypeScript" syntax	Starlight has built-in <Tabs> component
Custom Macros	macros.py (e.g., ts_not_supported())	Need to convert to Astro/MDX components
Snippets	--8<-- markers for external code	Will need alternative approach
API Reference	Auto-generated from sdk-python/sdk-typescript	Generated externally at build time

---

Clarifying Questions

1. Error Page Requirement

"Error page renders successfully"

I couldn't find an error page (404.md or similar) in the current docs. Could you clarify:

• Is there an existing error page that I missed?
• Or should I create a default 404 page for Starlight?

2. API Documentation & Search Exclusion

"Search excludes API documentation"

The API docs appear to be auto-generated at build time:

• Python API: Generated by build-py-docs.py from the sdk-python repo
• TypeScript API: Generated by typedoc from sdk-typescript

Questions:

• Should the Starlight migration include the API doc generation process?
• Or should API docs remain as external links (current: api-reference/typescript/index.html)?
• If included, how should search exclusion be implemented in Starlight?

3. Navigation & Content Scope

The mkdocs.yml defines extensive navigation with 100+ entries. Should I:

• Migrate the full navigation structure exactly as-is?
• Read navigation from mkdocs.yml programmatically (as mentioned in issue)?
• Or simplify for the initial default theme implementation?

4. Custom Features Migration

Should these MkDocs-specific features be migrated or deferred?

• Tabbed content (Python/TypeScript code tabs)
• Custom macros (ts_not_supported(), ts_not_supported_code())
• Snippet includes (--8<-- markers for TypeScript files)
• Extra CSS (docs/stylesheets/extra.css)
• Mike versioning (version selector functionality)

5. Branch Strategy Confirmation

The issue mentions creating on a new_docs branch. Should I:

• Create a fresh Astro/Starlight project structure?
• Keep any existing files from main (like assets, markdown)?

---

Implementation Assessment

This migration is feasible for a single developer in approximately 4-5 days, with the following breakdown:

• Day 1: Starlight project setup, navigation parsing
• Day 2-3: Content migration, mermaid/tabs configuration
• Day 4: Search exclusion, error page, testing
• Day 5: Polish and documentation

Please respond to the questions above and I'll refine the implementation requirements.

[zastrowm]

/strands

Clarifying Questions

1. Error Page Requirement

"Error page renders successfully"

I couldn't find an error page (404.md or similar) in the current docs. Could you clarify:

• Is there an existing error page that I missed?
• Or should I create a default 404 page for Starlight?

Use the default 404 page. If Starlight includes one, then great

2. API Documentation & Search Exclusion

"Search excludes API documentation"

The API docs appear to be auto-generated at build time:

• Python API: Generated by build-py-docs.py from the sdk-python repo
• TypeScript API: Generated by typedoc from sdk-typescript

Questions:

• Should the Starlight migration include the API doc generation process?
• Or should API docs remain as external links (current: api-reference/typescript/index.html)?
• If included, how should search exclusion be implemented in Starlight?

For now, skip API generation. We'll do that in a follow-up

3. Navigation & Content Scope

The mkdocs.yml defines extensive navigation with 100+ entries. Should I:

• Migrate the full navigation structure exactly as-is?
• Read navigation from mkdocs.yml programmatically (as mentioned in issue)?
• Or simplify for the initial default theme implementation?

Read navigation from mkdocs.yml programmatically

4. Custom Features Migration

Should these MkDocs-specific features be migrated or deferred?

• Tabbed content (Python/TypeScript code tabs)[ ] Custom macros (ts_not_supported(), ts_not_supported_code())[ ] Snippet includes (--8<-- markers for TypeScript files)[ ] Extra CSS (docs/stylesheets/extra.css)[ ] Mike versioning (version selector functionality)

Ignore version selection.

If we can do replacement macros easily, do so for now (we'll replace them eventually, but for now keeping as-is will make merges simpler)

5. Branch Strategy Confirmation

The issue mentions creating on a new_docs branch. Should I:

• Create a fresh Astro/Starlight project structure?
• Keep any existing files from main (like assets, markdown)?

Both; we want both astro and mkdocs running side by side for now; we'll migrate/ditch mkdocs later

Implementation Assessment

This migration is feasible for a single developer in approximately 4-5 days, with the following breakdown:

• Day 1: Starlight project setup, navigation parsing
• Day 2-3: Content migration, mermaid/tabs configuration
• Day 4: Search exclusion, error page, testing
• Day 5: Polish and documentation

Please respond to the questions above and I'll refine the implementation requirements.

[zastrowm]

/strands implement