Also covers multi-language documentation with hreflang support and Content Layer API integration (docsLoader, schema) specific to Starlight's content model, plus CSS custom property theming. Does not cover generic Astro Content Layer usage outside Starlight (astro-content) or non-Starlight i18n routing (astro-i18n) — those are handled by their own skills.
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, spawn 3 agents in parallel, one Agent call each with a name:
- 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 7 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-starlight3description: Use when building a documentation site with Astro Starlight — sidebar config, Pagefind search, plugins (blog/openapi/typedoc), i18n, llms.txt.4---56<objective>7Sets up and customizes Astro Starlight (0.41+), the documentation theme built on Astro 7: filesystem-based or manual sidebar configuration, built-in Pagefind full-text search (or DocSearch for high-traffic/large docs), automatic dark/light mode, and the plugin ecosystem — `starlight-blog`, `starlight-openapi`, `starlight-typedoc`, `starlight-versions`, `starlight-llms-txt` for AI discoverability.89Also covers multi-language documentation with hreflang support and Content Layer API integration (`docsLoader`, schema) specific to Starlight's content model, plus CSS custom property theming. Does not cover generic Astro Content Layer usage outside Starlight (astro-content) or non-Starlight i18n routing (astro-i18n) — those are handled by their own skills.10</objective>1112# Astro Starlight1314Production-ready documentation theme for Astro with built-in search, dark mode, i18n, and rich plugin ecosystem.1516## Agent Workflow (MANDATORY)1718Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:19201. **fuse-ai-pilot:explore-codebase** - Analyze existing Starlight config, sidebar, and content structure212. **fuse-ai-pilot:research-expert** - Verify Starlight plugin APIs via Context7/Exa223. **mcp__context7__query-docs** - Check Starlight docs for Content Layer and i18n patterns2324After implementation, run **fuse-ai-pilot:sniper** for validation.2526---2728## Overview2930### When to Use3132- Building technical documentation sites33- Creating API reference docs (with starlight-openapi)34- Generating docs from TypeScript types (with starlight-typedoc)35- Adding a blog to a documentation site (with starlight-blog)36- Setting up versioned documentation (with starlight-versions)37- Multi-language documentation with hreflang support3839### Why Starlight4041| Feature | Benefit |42|---------|---------|43| Pagefind built-in | Full-text search, zero config |44| Dark/light mode | Automatic, CSS custom properties |45| Sidebar config | Filesystem-based or manual groups |46| Plugin ecosystem | DocSearch, blog, openapi, typedoc |47| Content Layer API | Astro 7 content collections integration |48| llms.txt support | `starlight-llms-txt` for AI discoverability |4950---5152## Reference Guide5354### Concepts5556| Topic | Reference | When to Consult |57|-------|-----------|-----------------|58| **Setup** | [setup.md](references/setup.md) | Installation, project structure |59| **Sidebar** | [sidebar-config.md](references/sidebar-config.md) | Navigation, groups, auto-gen |60| **Search** | [search.md](references/search.md) | Pagefind, DocSearch, exclude pages |61| **Plugins** | [plugins.md](references/plugins.md) | Blog, openapi, typedoc, versions |62| **i18n** | [i18n-multilang.md](references/i18n-multilang.md) | Locales, translations, hreflang |63| **Content Layer** | [content-layer.md](references/content-layer.md) | docsLoader, schema, collections |64| **Customization** | [customization.md](references/customization.md) | CSS variables, components override |6566### Templates6768| Template | When to Use |69|----------|-------------|70| [starlight-config.md](references/templates/starlight-config.md) | Full astro.config.mjs with Starlight |71| [sidebar-example.md](references/templates/sidebar-example.md) | Complex sidebar with groups and badges |7273---7475## Best Practices76771. **Start with filesystem sidebar** - Add manual config only when needed782. **Keep Pagefind for small sites** - DocSearch for high-traffic or large docs793. **Use `starlight-llms-txt`** - AI crawlers increasingly important for docs804. **Content Layer schema** - Type-safe frontmatter prevents runtime errors815. **CSS custom properties** - Override theme without component slots
fusengine