Astro Starlight
Production-ready documentation theme for Astro with built-in search, dark mode, i18n, and rich plugin ecosystem.
Agent Workflow (MANDATORY)
Before ANY implementation, use TeamCreate to spawn 3 agents:
- fuse-ai-pilot:explore-codebase - Analyze existing Starlight config, sidebar, and content structure
- fuse-ai-pilot:research-expert - Verify Starlight plugin APIs via Context7/Exa
- mcp__context7__query-docs - Check Starlight docs for Content Layer and i18n patterns
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
When to Use
- Building technical documentation sites
- Creating API reference docs (with starlight-openapi)
- Generating docs from TypeScript types (with starlight-typedoc)
- Adding a blog to a documentation site (with starlight-blog)
- Setting up versioned documentation (with starlight-versions)
- Multi-language documentation with hreflang support
Why Starlight
| Feature | Benefit |
|---|---|
| Pagefind built-in | Full-text search, zero config |
| Dark/light mode | Automatic, CSS custom properties |
| Sidebar config | Filesystem-based or manual groups |
| Plugin ecosystem | DocSearch, blog, openapi, typedoc |
| Content Layer API | Astro 6 content collections integration |
| llms.txt support | starlight-llms-txt for AI discoverability |
Reference Guide
Concepts
| Topic | Reference | When to Consult |
|---|---|---|
| Setup | setup.md | Installation, project structure |
| Sidebar | sidebar-config.md | Navigation, groups, auto-gen |
| Search | search.md | Pagefind, DocSearch, exclude pages |
| Plugins | plugins.md | Blog, openapi, typedoc, versions |
| i18n | i18n-multilang.md | Locales, translations, hreflang |
| Content Layer | content-layer.md | docsLoader, schema, collections |
| Customization | customization.md | CSS variables, components override |
Templates
| Template | When to Use |
|---|---|
| starlight-config.md | Full astro.config.mjs with Starlight |
| sidebar-example.md | Complex sidebar with groups and badges |
Best Practices
- Start with filesystem sidebar - Add manual config only when needed
- Keep Pagefind for small sites - DocSearch for high-traffic or large docs
- Use
starlight-llms-txt- AI crawlers increasingly important for docs - Content Layer schema - Type-safe frontmatter prevents runtime errors
- CSS custom properties - Override theme without component slots