Skip to main content
Frontend Developmentfusengine

astro-starlight

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.

Stars
13
Source
fusengine/agents
Updated
2026-05-17
Slug
fusengine--agents--astro-starlight
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/fusengine/agents/HEAD/plugins/astro-expert/skills/astro-starlight/SKILL.md -o .claude/skills/astro-starlight.md

Drops the SKILL.md into .claude/skills/astro-starlight.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Sets 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.

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:

  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

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

  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