AgentSkillsCN

astro-starlight

Astro Starlight 文档主题——设置、侧边栏配置、Pagefind 搜索、深浅模式、插件（DocSearch、博客、openapi、typedoc、版本）、多语言、内容层 API、llms.txt、定制。适用于构建文档网站时使用。

SKILL.md
--- frontmatter
name: astro-starlight
description: 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.
versions:
  astro: "6"
  starlight: "0.38+"
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-6, astro-content, astro-i18n, astro-seo

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:

  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

FeatureBenefit
Pagefind built-inFull-text search, zero config
Dark/light modeAutomatic, CSS custom properties
Sidebar configFilesystem-based or manual groups
Plugin ecosystemDocSearch, blog, openapi, typedoc
Content Layer APIAstro 6 content collections integration
llms.txt supportstarlight-llms-txt for AI discoverability

Reference Guide

Concepts

TopicReferenceWhen to Consult
Setupsetup.mdInstallation, project structure
Sidebarsidebar-config.mdNavigation, groups, auto-gen
Searchsearch.mdPagefind, DocSearch, exclude pages
Pluginsplugins.mdBlog, openapi, typedoc, versions
i18ni18n-multilang.mdLocales, translations, hreflang
Content Layercontent-layer.mddocsLoader, schema, collections
Customizationcustomization.mdCSS variables, components override

Templates

TemplateWhen to Use
starlight-config.mdFull astro.config.mjs with Starlight
sidebar-example.mdComplex 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