astro-starlight

搭建并自定义 Astro Starlight（0.42+，最新版本为 0.42.4；要求 Astro 7.2.10+——0.41 已不再支持 Astro 6）。这是一款基于 Astro 7 构建的文档主题，支持基于文件系统或手动配置侧边栏、内置 Pagefind 全文搜索（或适用于高流量／大型文档的 DocSearch）、自动深色／浅色模式，以及丰富的插件生态系统——`starlight-blog`、`starlight-openapi`、`starlight-typedoc`、`starlight-versions`、`starlight-llms-txt`，助力 AI 发现文档。

还涵盖支持 hreflang 的多语言文档，以及与 Starlight 内容模型相关的 Content Layer API 集成（docsLoader、schema），还有 CSS 自定义属性主题配置。不涵盖 Starlight 以外的通用 Astro Content Layer 用法（astro-content）或非 Starlight 国际化路由（astro-i18n）——这些由各自的技能处理。

Astro Starlight

适用于 Astro 的生产就绪文档主题，内置搜索、深色模式、国际化和丰富的插件生态系统。

Agent 工作流（必须遵循）

在进行任何实现之前，先并行启动 3 个 Agent，每个分别调用一次 Agent，并指定 name：

1. fuse-ai-pilot:explore-codebase - 分析现有的 Starlight 配置、侧边栏和内容结构
2. fuse-ai-pilot:research-expert - 通过 Context7/Exa 验证 Starlight 插件 API
3. mcp__context7__query-docs - 查看 Starlight 文档中的 Content Layer 和国际化模式

实现后，运行 fuse-ai-pilot:sniper 进行验证。

---

概览

适用场景

• 构建技术文档站点
• 创建 API 参考文档（使用 starlight-openapi）
• 根据 TypeScript 类型生成文档（使用 starlight-typedoc）
• 为文档站点添加博客（使用 starlight-blog）
• 设置版本化文档（使用 starlight-versions）
• 创建支持 hreflang 的多语言文档

为什么选择 Starlight

特性	优势
内置 Pagefind	全文搜索，无需配置
深色／浅色模式	自动切换，支持 CSS 自定义属性
侧边栏配置	基于文件系统，或手动配置分组
插件生态系统	DocSearch、博客、openapi、typedoc
Content Layer API	集成 Astro 7 内容集合
支持 llms.txt	使用 starlight-llms-txt 提升 AI 对文档的发现能力
无需 JS 的移动菜单（0.42）	Popover API——禁用 JS 后菜单仍可用；提供编译后的 JS + .d.ts（加快 tsc）

---

参考指南

概念

主题	参考资料	查阅时机
设置	setup.md	安装、项目结构
侧边栏	sidebar-config.md	导航、分组、自动生成
搜索	search.md	Pagefind、DocSearch、排除页面
插件	plugins.md	博客、openapi、typedoc、版本
国际化	i18n-multilang.md	语言区域、翻译、hreflang
Content Layer	content-layer.md	docsLoader、schema、集合
自定义	customization.md	CSS 变量、覆盖组件

模板

模板	适用场景
starlight-config.md	完整的、包含 Starlight 的 astro.config.mjs
sidebar-example.md	带分组和徽章的复杂侧边栏

---

最佳实践

1. 从基于文件系统的侧边栏开始 - 仅在需要时添加手动配置
2. 小型站点使用 Pagefind - 高流量或大型文档使用 DocSearch
3. 使用 starlight-llms-txt - AI 爬虫对文档越来越重要
4. 配置 Content Layer schema - 类型安全的 frontmatter 可防止运行时错误
5. 使用 CSS 自定义属性 - 无需组件插槽即可覆盖主题