feat: add Starlight/Astro documentation site

[github-actions]

Summary

This PR adds a new Starlight/Astro-based documentation site using the existing docs/ directory as the content source (via symlink). This ensures a single source of truth for documentation while providing a modern documentation experience.

Changes

Starlight Framework Setup

• Project Configuration: Astro/Starlight project in starlight/ directory
• Content Symlink: starlight/src/content/docs → ../../docs (no content duplication)
• Frontmatter: Added title frontmatter to all markdown files for Starlight compatibility
• Homepage: Renamed docs/README.md to docs/index.md for Starlight homepage

Features

• Search: Pagefind search with 10,179 indexed words across 135 pages
• Mermaid Support: Client-side rendering via CDN
• Dark/Light Mode: Automatic theme switching with custom brand colors
• Sidebar Navigation: Structured navigation based on mkdocs.yml layout

Running Locally

cd starlight
npm install
npm run dev    # Development server at localhost:4321
npm run build  # Production build

Key Design Decisions

• Symlink approach: Content lives in original docs/ directory, Starlight uses symlink
• Frontmatter compatibility: All markdown files now have frontmatter that works with both mkdocs and Starlight
• No content duplication: Single source of truth for all documentation

Testing Checklist

• Build completes successfully (136 pages)
• Dev server starts without errors
• Search indexes all pages
• Navigation structure matches requirements
• No content duplication

Resolves #5

[zastrowm]

/strands

[zastrowm]

All the content MUST live where it originally was. If we can't have them working side by side, then just update the content to be starlight only. Apply this guidance to all markdown files - we do not want separate copies of everything!

[github-actions]

Understood! I'll reconfigure Starlight to use the original docs/ directory as the content source instead of duplicating files. Will update the markdown files in place with frontmatter.

[zastrowm]

/strands

[zastrowm]

Can we get away with not modifying the files, by generating the titles from these at build time by readingh the markdown and extracting the first header?

Or could we update the starlight template to not require a title field?

[github-actions]

Good point! I'll investigate using a custom Starlight schema that auto-generates titles from the first markdown heading at build time, avoiding source file modifications.

[github-actions]

Great suggestion! I'll create an inline loader that reads titles from mkdocs.yml navigation structure. This avoids modifying any source files.

[zastrowm]

/strands

[github-actions]

Investigation Update: Auto-Title Generation

I've investigated several approaches to avoid adding frontmatter to the markdown files:

1. Custom Schema with Optional Title - The schema's .default() provides "Untitled" but can't extract from H1 headings
2. Custom Content Loader - Post-processing happens after schema validation, so we can't inject extracted titles
3. Remark Plugin - Runs after content collection validation, too late to add titles

Finding: Starlight's architecture validates frontmatter before markdown processing, making runtime title extraction technically complex.

Proposed Solutions:

Option A: Keep Minimal Frontmatter (Recommended)

• Add only title field in frontmatter (what we have now)
• This is backwards-compatible with mkdocs (mkdocs handles YAML frontmatter)
• Single source of truth maintained
• Titles explicitly declared rather than inferred

Option B: Pre-build Script

• Script generates a temp copy with injected frontmatter
• Starlight points to temp location
• Adds build complexity

Option C: Accept "Untitled" Pages

• Pages work but show "Untitled" in titles
• Navigation uses sidebar config labels instead

Which approach would you prefer? I recommend Option A since the frontmatter is already compatible with both mkdocs and Starlight.

[zastrowm]

/strands

Per the documentation at https://docs.astro.build/en/guides/content-collections/ can we define our own content collection using an inline loader and use that to populate the title from the mkdocs.yml file?

[github-actions]

Investigation Results: Inline Loader Approach

I've thoroughly investigated the inline loader approach per your suggestion. Here's what I found:

Approaches Attempted:

1. Inline loader - Returns data correctly but doesn't render markdown (pages have no body content)
2. Object loader wrapping glob() - Schema validation happens inside glob's syncData before my post-processing can inject titles

Technical Constraint:

Starlight/Astro validates frontmatter schemas during the glob loader's file processing, not after. This means:

• We can't post-process entries to add titles
• The title field must exist in the file before schema validation runs

Options:

A. Minimal Frontmatter (Current solution)

---
title: "Page Title"  
---

• ✅ Works with both mkdocs and Starlight
• ✅ Single source of truth maintained
• ✅ Titles derived from mkdocs.yml nav (added via script)
• ⚠️ Requires frontmatter in source files

B. Pre-build Script

• Script copies docs → temp with injected frontmatter
• Starlight reads from temp location
• ❌ Adds complexity, temp file management

C. Fork Starlight's docsLoader

• Create custom loader that injects titles before validation
• ❌ Maintenance burden, Starlight updates

I recommend Option A - the minimal frontmatter is backwards-compatible with mkdocs and represents the cleanest solution given Starlight's architecture.