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
1---2name: astro-starlight-33description: Astro Starlight documentation theme — setup, sidebar config, Pagefind search, dark/light mode, plugins (DocSearch, blog, openapi, typedoc, versions), multi-language, Content Layer API, llms.txt, customization. Use for building documentation sites.4---56# Astro Starlight78Production-ready documentation theme for Astro with built-in search, dark mode, i18n, and rich plugin ecosystem.910## Agent Workflow (MANDATORY)1112Before ANY implementation, use `TeamCreate` to spawn 3 agents:13141. **fuse-ai-pilot:explore-codebase** - Analyze existing Starlight config, sidebar, and content structure152. **fuse-ai-pilot:research-expert** - Verify Starlight plugin APIs via Context7/Exa163. **mcp__context7__query-docs** - Check Starlight docs for Content Layer and i18n patterns1718After implementation, run **fuse-ai-pilot:sniper** for validation.1920---2122## Overview2324### When to Use2526- Building technical documentation sites27- Creating API reference docs (with starlight-openapi)28- Generating docs from TypeScript types (with starlight-typedoc)29- Adding a blog to a documentation site (with starlight-blog)30- Setting up versioned documentation (with starlight-versions)31- Multi-language documentation with hreflang support3233### Why Starlight3435| Feature | Benefit |36|---------|---------|37| Pagefind built-in | Full-text search, zero config |38| Dark/light mode | Automatic, CSS custom properties |39| Sidebar config | Filesystem-based or manual groups |40| Plugin ecosystem | DocSearch, blog, openapi, typedoc |41| Content Layer API | Astro 6 content collections integration |42| llms.txt support | `starlight-llms-txt` for AI discoverability |4344---4546## Reference Guide4748### Concepts4950| Topic | Reference | When to Consult |51|-------|-----------|-----------------|52| **Setup** | [setup.md](references/setup.md) | Installation, project structure |53| **Sidebar** | [sidebar-config.md](references/sidebar-config.md) | Navigation, groups, auto-gen |54| **Search** | [search.md](references/search.md) | Pagefind, DocSearch, exclude pages |55| **Plugins** | [plugins.md](references/plugins.md) | Blog, openapi, typedoc, versions |56| **i18n** | [i18n-multilang.md](references/i18n-multilang.md) | Locales, translations, hreflang |57| **Content Layer** | [content-layer.md](references/content-layer.md) | docsLoader, schema, collections |58| **Customization** | [customization.md](references/customization.md) | CSS variables, components override |5960### Templates6162| Template | When to Use |63|----------|-------------|64| [starlight-config.md](references/templates/starlight-config.md) | Full astro.config.mjs with Starlight |65| [sidebar-example.md](references/templates/sidebar-example.md) | Complex sidebar with groups and badges |6667---6869## Best Practices70711. **Start with filesystem sidebar** - Add manual config only when needed722. **Keep Pagefind for small sites** - DocSearch for high-traffic or large docs733. **Use `starlight-llms-txt`** - AI crawlers increasingly important for docs744. **Content Layer schema** - Type-safe frontmatter prevents runtime errors755. **CSS custom properties** - Override theme without component slots
fusengine