Astro Starlight Skill

Build production-grade documentation sites with Astro Starlight. This skill covers everything from initial scaffolding to advanced customization and deployment.

When to use this skill

- Creating a new documentation site from scratch
Adding Starlight to an existing Astro project
Configuring sidebar navigation (manual, autogenerated, or mixed)
Styling/theming a Starlight site (custom CSS, Tailwind, dark mode)
Using MDX components inside docs (Tabs, Cards, Asides, Code, etc.)
Deploying to subpaths (/docs/), Vercel, Netlify, Cloudflare Pages
Setting up search (Pagefind, Algolia)
Internationalization (i18n)
Overriding built-in components
Troubleshooting common issues (404s, broken links, sidebar mismatches)

Quick orientation

Before writing any code, read the relevant reference file(s) from references/:

Task	Read first
New project or project structure	INLINECODE2
Sidebar, navigation, frontmatter

For most tasks, read project-setup.md first, then the topic-specific file.

Core workflow

1. Scaffold the project

CODEBLOCK0

This gives you a working project with:
CODEBLOCK1

2. Design folder structure FIRST

This is the most important step. Your folder structure = your URL structure = your sidebar structure. Plan it before writing content. See references/sidebar-and-content.md for patterns.

3. Configure `astro.config.mjs`

The Starlight integration is configured here. Minimum viable config:

CODEBLOCK2

4. Write content in `src/content/docs/`

Every .md or .mdx file needs frontmatter with at least title:

CODEBLOCK3

5. Build and deploy

CODEBLOCK4

Key principles

1. Design folder structure before writing content. Restructuring later means broken links and sidebar chaos.
Keep sidebar config explicit rather than fully auto-generated — you'll want control over ordering and grouping.
Use .mdx only when you need component imports. Plain .md is simpler and avoids hydration issues.
Test deployment early, especially if hosting at a subpath. Don't wait until the end.
Keep CSS overrides minimal. Work with Starlight's design tokens (CSS custom properties) rather than fighting its defaults.
Use frontmatter sidebar.order to control page ordering within autogenerated groups.

Important gotchas (read these)

- Subpath deployment is the #1 source of bugs. If deploying to /docs/, you must set both site and base in astro.config.mjs. See references/deployment-and-advanced.md.
MDX imports only work in .mdx files, not .md. If you get import errors, check your file extension.
Sidebar config and filesystem must agree. A page that exists on disk but isn't in the sidebar config (or vice versa) causes confusing 404s or missing nav items.
Tailwind + Starlight requires the @astrojs/starlight-tailwind compatibility package. Without it, styles will fight each other.
Pagefind search breaks on subpaths if base isn't configured correctly.
Custom components need client:load (or another client directive) if they use JavaScript/interactivity. Without it, they render as static HTML only.

Reference files

Read these for detailed guidance. Each is self-contained and covers one topic area thoroughly:

- references/project-setup.md — Scaffolding, project structure, astro.config.mjs anatomy, content collections
INLINECODE30 — Sidebar config patterns, frontmatter reference, content authoring, ordering
INLINECODE31 — Custom CSS, Tailwind integration, theming, dark mode, Expressive Code
INLINECODE32 — Built-in components (Tabs, Cards, Asides, etc.), custom components in MDX, hydration
INLINECODE33 — Deployment targets, subpath hosting, search, i18n, versioning, auth, SSR
INLINECODE34 — Diagnosis and fixes for the most common Starlight issues

Useful links

- Docs: https://starlight.astro.build
GitHub: https://github.com/withastro/starlight
Config reference: https://starlight.astro.build/reference/configuration/
Frontmatter reference: https://starlight.astro.build/reference/frontmatter/
Component list: https://starlight.astro.build/components/using-components/
Community plugins: https://starlight.astro.build/resources/plugins/

Astro Starlight 技能

使用 Astro Starlight 构建生产级文档站点。本技能涵盖从初始脚手架搭建到高级自定义和部署的所有内容。

何时使用本技能

- 从头创建新的文档站点
将 Starlight 添加到现有 Astro 项目
配置侧边栏导航（手动、自动生成或混合模式）
为 Starlight 站点设置样式/主题（自定义 CSS、Tailwind、暗色模式）
在文档中使用 MDX 组件（标签页、卡片、旁注、代码等）
部署到子路径（/docs/）、Vercel、Netlify、Cloudflare Pages
配置搜索（Pagefind、Algolia）
国际化（i18n）
覆盖内置组件
排查常见问题（404、链接失效、侧边栏不匹配）

快速入门

在编写任何代码之前，请先阅读 references/ 中的相关参考文件：

任务	优先阅读
新项目或项目结构	references/project-setup.md
侧边栏、导航、前置元数据

对于大多数任务，先阅读 project-setup.md，然后再阅读特定主题的文件。

核心工作流程

1. 脚手架搭建项目

bash
npm create astro@latest -- --template starlight

这将为您提供一个可运行的项目，结构如下：

my-docs/
├── astro.config.mjs # Starlight 集成配置
├── src/
│ ├── content/
│ │ └── docs/ # 所有文档页面存放于此
│ │ └── index.mdx
│ └── content.config.ts # 内容集合模式
├── public/ # 静态资源（favicon、图片）
└── package.json

2. 首先设计文件夹结构

这是最重要的一步。您的文件夹结构 = 您的 URL 结构 = 您的侧边栏结构。在编写内容之前先规划好。模式请参见 references/sidebar-and-content.md。

3. 配置 astro.config.mjs

Starlight 集成在此处配置。最小可行配置：

js
import { defineConfig } from astro/config;
import starlight from @astrojs/starlight;

export default defineConfig({
integrations: [
starlight({
title: 我的文档,
sidebar: [
{
label: 指南,
autogenerate: { directory: guides },
},
],
}),
],
});

4. 在 src/content/docs/ 中编写内容

每个 .md 或 .mdx 文件都需要包含至少 title 的前置元数据：

yaml

title: 入门指南
description: 如何开始使用我们的产品。
sidebar:
order: 1

5. 构建和部署

bash
npm run build # 输出到 dist/
npm run preview # 本地预览构建结果

关键原则

1. 在编写内容之前先设计文件夹结构。 后续重构会导致链接失效和侧边栏混乱。
保持侧边栏配置显式，而不是完全自动生成——您需要控制排序和分组。
仅在需要组件导入时使用 .mdx。 纯 .md 更简单，可避免水合问题。
尽早测试部署，尤其是在子路径托管时。不要等到最后。
保持 CSS 覆盖最小化。 使用 Starlight 的设计令牌（CSS 自定义属性），而不是与其默认样式对抗。
使用前置元数据 sidebar.order 来控制自动生成组内的页面排序。

重要注意事项（请阅读）

- 子路径部署是头号 Bug 来源。 如果部署到 /docs/，必须在 astro.config.mjs 中同时设置 site 和 base。请参见 references/deployment-and-advanced.md。
MDX 导入仅适用于 .mdx 文件，不适用于 .md。如果遇到导入错误，请检查文件扩展名。
侧边栏配置和文件系统必须一致。 磁盘上存在但侧边栏配置中没有的页面（反之亦然）会导致令人困惑的 404 或导航项缺失。
Tailwind + Starlight 需要 @astrojs/starlight-tailwind 兼容包。 否则样式会相互冲突。
如果 base 配置不正确，Pagefind 搜索在子路径上会失效。
自定义组件如果使用 JavaScript/交互功能，需要添加 client:load（或其他客户端指令）。否则它们只会渲染为静态 HTML。

参考文件

阅读以下文件获取详细指导。每个文件都是独立的，涵盖一个主题领域：

- references/project-setup.md — 脚手架搭建、项目结构、astro.config.mjs 解析、内容集合
references/sidebar-and-content.md — 侧边栏配置模式、前置元数据参考、内容编写、排序
references/styling-and-theming.md — 自定义 CSS、Tailwind 集成、主题、暗色模式、Expressive Code
references/components.md — 内置组件（标签页、卡片、旁注等）、MDX 中的自定义组件、水合
references/deployment-and-advanced.md — 部署目标、子路径托管、搜索、i18n、版本控制、认证、SSR
references/troubleshooting.md — 最常见 Starlight 问题的诊断和修复

实用链接

- 文档：https://starlight.astro.build
GitHub：https://github.com/withastro/starlight
配置参考：https://starlight.astro.build/reference/configuration/
前置元数据参考：https://starlight.astro.build/reference/frontmatter/
组件列表：https://starlight.astro.build/components/using-components/
社区插件：https://starlight.astro.build/resources/plugins/

astro-starlight星辉术

astro-starlight

Astro Starlight Skill

When to use this skill

Quick orientation