/astro-starlight

name: astro-starlight
description: Use when building a documentation site with Astro Starlight — sidebar config, Pagefind search, plugins (blog/openapi/typedoc), i18n, llms.txt.
versions:
  astro: "7"
  starlight: "0.42+"
user-invocable: true
references: references/setup.md, references/sidebar-config.md, references/search.md, references/plugins.md, references/i18n-multilang.md, references/content-layer.md, references/customization.md, references/templates/starlight-config.md, references/templates/sidebar-example.md
related-skills: astro-7, astro-content, astro-i18n, astro-seo

<objective> Sets up and customizes Astro Starlight (0.42+, latest 0.42.10; requires Astro 7.2.10+ — 0.41 dropped Astro 6), 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.

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. </objective>

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`:

1. **fuse-ai-pilot:explore-codebase** - Analyze existing Starlight config, sidebar, and content structure 2. **fuse-ai-pilot:research-expert** - Verify Starlight plugin APIs via Context7/Exa 3. **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 | | No-JS mobile menu (0.42) | Popover API — menu works with JS disabled; ships compiled JS + `.d.ts` (faster `tsc`) |

---

Reference Guide

Concepts

| Topic | Reference | When to Consult | |-------|-----------|-----------------| | **Setup** | [setup.md](references/setup.md) | Installation, project structure | | **Sidebar** | [sidebar-config.md](references/sidebar-config.md) | Navigation, groups, auto-gen | | **Search** | [search.md](references/search.md) | Pagefind, DocSearch, exclude pages | | **Plugins** | [plugins.md](references/plugins.md) | Blog, openapi, typedoc, versions | | **i18n** | [i18n-multilang.md](references/i18n-multilang.md) | Locales, translations, hreflang | | **Content Layer** | [content-layer.md](references/content-layer.md) | docsLoader, schema, collections | | **Customization** | [customization.md](references/customization.md) | CSS variables, components override |

Templates

| Template | When to Use | |----------|-------------| | [starlight-config.md](references/templates/starlight-config.md) | Full astro.config.mjs with Starlight | | [sidebar-example.md](references/templates/sidebar-example.md) | Complex sidebar with groups and badges |

---

Best Practices

1. **Start with filesystem sidebar** - Add manual config only when needed 2. **Keep Pagefind for small sites** - DocSearch for high-traffic or large docs 3. **Use `starlight-llms-txt`** - AI crawlers increasingly important for docs 4. **Content Layer schema** - Type-safe frontmatter prevents runtime errors 5. **CSS custom properties** - Override theme without component slots