illegalCreed

中文

English

中文

English

Appearance

参考 ​

基于 Starlight 0.36.x（跟随 Astro 5.x）。本页是 API 速查——CLI、配置字段、Frontmatter、内置组件 props、CSS 变量、可覆盖组件、Plugin API 等。

CLI 命令 ​

Starlight 没有独立 CLI——使用 Astro CLI。所有命令通过 astro 子命令调用。

基础命令 ​

bash
pnpm astro dev          # 启动 dev server（默认 4321 端口）
pnpm astro build        # 生产构建到 dist/
pnpm astro preview      # 本地预览 dist/（生产模式）
pnpm astro check        # 类型 / Zod schema 静态检查
pnpm astro sync         # 重新生成 src/env.d.ts 类型
pnpm astro add <name>   # 添加集成（如 astro add starlight）
pnpm astro telemetry    # 控制匿名遥测
pnpm astro info         # 打印环境信息（用于报 bug）
pnpm astro --help       # 查看所有命令

astro dev 选项 ​

选项默认作用
--port <num>4321自定义端口
--host <addr>localhost自定义 host（0.0.0.0 允许局域网访问）
--opentrue自动打开浏览器（--open false 关闭）
--config <file>astro.config.mjs指定配置文件
--root <dir>.项目根目录
--verbosefalseverbose 日志
--silentfalse静默模式

astro build 选项 ​

选项默认作用
--outDir <dir>dist输出目录
--site <url>astro.config.mjs.site覆盖站点 URL

astro add 集成示例 ​

bash
pnpm astro add starlight          # 添加 Starlight 集成
pnpm astro add mdx                # 添加 MDX 支持
pnpm astro add markdoc            # 添加 Markdoc 支持
pnpm astro add sitemap            # 添加 sitemap.xml 生成
pnpm astro add react              # 添加 React 集成
pnpm astro add vue                # 添加 Vue 集成
pnpm astro add svelte             # 添加 Svelte 集成
pnpm astro add solid              # 添加 Solid 集成
pnpm astro add tailwind           # 添加 Tailwind v4 集成
pnpm astro add node               # 添加 Node SSR adapter
pnpm astro add vercel             # 添加 Vercel adapter
pnpm astro add netlify            # 添加 Netlify adapter
pnpm astro add cloudflare         # 添加 Cloudflare adapter

astro.config.mjs 字段 ​

Astro 站点级字段 ​

字段类型默认作用
sitestring-生产 URL（sitemap / canonical / OG 用）
basestring/子路径前缀（GitHub Pages 等）
trailingSlash'always' | 'never' | 'ignore''ignore'URL 末尾 / 处理
output'static' | 'server''static'静态构建 / SSR
adapterobject-SSR 适配器（vercel / netlify / node 等）
integrationsarray[]Astro 集成（starlight 在此）
viteobject-Vite 配置透传
markdownobject-Markdown 处理选项（remarkPlugins / rehypePlugins / shikiConfig）
srcDirstring./src源码目录
publicDirstring./public静态资源目录
outDirstring./dist构建输出目录
prefetchboolean | object-预取相邻页面
compressHTMLbooleantrue压缩 HTML 输出
redirectsRecord-静态重定向（{ '/old': '/new' }）

Starlight 集成字段 ​

调用 starlight({ ... }) 传入：

字段类型默认作用
titlestring | Record必填站点标题（可按 locale 多语言对象）
descriptionstring-meta description
taglinestring-默认 hero tagline
logoobject-Logo（src / light / dark / alt / replacesTitle）
faviconstring/favicon.svgFavicon 路径（相对 public/）
headarray[]额外 <head> 标签
langstring'en'单语言时的语言代码
defaultLocalestring-默认语言（多语言时必填）
localesRecord-多语言配置
socialarray[]社交链接
sidebararray-侧边栏导航配置
customCssstring[][]自定义 CSS 文件路径
pagefindboolean | objecttrue内置搜索（false 禁用）
componentsRecord-覆盖内置组件（{ Header: './path.astro' }）
pluginsarray[]Starlight 插件列表
editLinkobject-编辑链接（{ baseUrl: '...' }）
lastUpdatedbooleanfalse显示页脚 last updated 日期
paginationbooleantrue显示页脚 prev/next 导航
expressiveCodeobject | booleantrueExpressive Code 配置（false 禁用）
markdownobject-Markdown 配置（headingLinks / processedDirs）
prerenderbooleantrue预渲染（SSR 模式下用）
disable404Routebooleanfalse禁用默认 404 路由
creditsbooleanfalse显示 "Built with Starlight"
tableOfContentsobject | false{ minHeadingLevel: 2, maxHeadingLevel: 3 }右侧目录配置
routeMiddlewarestring | string[]-Route middleware 文件路径
titleDelimiterstring'|'浏览器标签分隔符

Logo 字段 ​

ts
{
  src?: string;             // 单 logo（不分明暗）
  light?: string;           // 明色模式 logo
  dark?: string;            // 暗色模式 logo
  alt?: string;             // alt 文字
  replacesTitle?: boolean;  // true: 替代标题文字
}

Locales 字段 ​

ts
locales: {
  // 普通 locale
  en: {
    label: string;     // 必填，下拉选择显示
    lang?: string;     // BCP-47 语言代码（如 'en' / 'zh-CN'）
    dir?: 'ltr' | 'rtl';
  };

  // root locale（无 URL 前缀的默认语言）
  root?: {
    label: string;
    lang: string;      // root locale 时 lang 必填
    dir?: 'ltr' | 'rtl';
  };
}

每个 sidebar 项目是以下三种之一：

Link（内部 / 外部链接）：

ts
{
  label: string;
  slug?: string;          // 内部页面 slug（如 'guides/install'）
  link?: string;          // 外部 URL
  badge?: { text: string; variant?: 'note' | 'tip' | 'success' | 'caution' | 'danger' | 'default'; class?: string };
  attrs?: Record<string, string>;
  translations?: Record<string, string>;
}

Group（嵌套分组）：

ts
{
  label: string;
  items: SidebarItem[];
  collapsed?: boolean;
  badge?: { text: string; variant?: ... };
  translations?: Record<string, string>;
}

Autogenerate（自动生成）：

ts
{
  label: string;
  autogenerate: {
    directory: string;     // src/content/docs/ 下的子目录
    collapsed?: boolean;
    attrs?: Record<string, string>;
  };
}

Social 字段 ​

ts
social: Array<{
  label: string;
  icon: SocialIconName;
  href: string;
}>;

可用 SocialIconName（部分）：

github  gitlab  gitea  codeberg  bitbucket
discord  mastodon  bluesky  x.com  twitter  threads
youtube  twitch  instagram  facebook  linkedin
patreon  ko-fi  buy-me-a-coffee
email  rss  blueSky  hackerNews
ts
editLink: {
  baseUrl: string;   // 编辑 URL 基址（自动追加 src/content/docs/... 路径）
}

例子：

ts
{ baseUrl: 'https://github.com/myorg/docs/edit/main/' }
// 自动生成：https://github.com/myorg/docs/edit/main/src/content/docs/guides/install.md

Components 字段（覆盖默认组件） ​

ts
components: {
  // 键：被覆盖的组件名
  // 值：自定义 .astro 文件路径
  Header: './src/components/MyHeader.astro';
  Footer: './src/components/MyFooter.astro';
  EditLink: './src/components/MyEditLink.astro';
  // 等...
}

Plugins 字段 ​

ts
plugins: StarlightPlugin[];

interface StarlightPlugin {
  name: string;
  hooks: {
    'config:setup'?: (options: ConfigSetupOptions) => void | Promise<void>;
    'i18n:setup'?: (options: I18nSetupOptions) => void | Promise<void>;
  };
}

Content Collections schema ​

docsLoader() + docsSchema() ​

ts
// src/content.config.ts
import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({
    loader: docsLoader(),
    schema: docsSchema(),
  }),
};

docsLoader() 选项：

选项类型默认作用
generateIdfunction-自定义 ID 生成器

docsSchema() 选项：

选项类型作用
extendZod schema扩展默认 frontmatter（追加自定义字段）
imagefunctionimage 处理器（用于 hero.image）

i18nLoader() + i18nSchema() ​

ts
import { i18nLoader } from '@astrojs/starlight/loaders';
import { i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  i18n: defineCollection({
    loader: i18nLoader(),
    schema: i18nSchema(),
  }),
};

i18nSchema() 选项：

选项类型作用
extendZod schema扩展默认翻译字段（追加自定义 UI 字符串）

Frontmatter 字段 ​

yaml
---
# 基础
title: string                   # 必填
description: string             # SEO meta description
slug: string                    # 自定义 URL slug

# 模板 / 布局
template: 'doc' | 'splash'      # 默认 'doc'

# Hero（splash 模板用）
hero:
  title: string
  tagline: string
  image:
    alt: string
    file: string               # 单图（不分明暗）
    light: string              # 明色 logo
    dark: string               # 暗色 logo
    html: string               # 直接 inline HTML（如 SVG）
  actions:
    - text: string
      link: string
      icon: string
      variant: 'primary' | 'secondary' | 'minimal'
      attrs:
        target: '_blank'

# Banner（顶部横幅）
banner:
  content: string              # 支持 HTML

# Table of Contents
tableOfContents: false | { minHeadingLevel: 2, maxHeadingLevel: 3 }

# 编辑链接
editUrl: string | boolean      # 单页覆盖 / 禁用

# Last Updated
lastUpdated: Date | boolean    # 单页覆盖 / 禁用

# 导航
prev: true | false | { link: string; label?: string }
next: true | false | { link: string; label?: string }

# Sidebar
sidebar:
  label: string                # 覆盖 sidebar 显示文字
  order: number                # 排序权重
  hidden: boolean              # autogenerate 时隐藏
  badge:
    text: string
    variant: 'note' | 'tip' | 'success' | 'caution' | 'danger' | 'default'
  attrs:
    target: '_blank'

# Head 注入
head:
  - tag: string                # 标签名（meta / link / script）
    attrs:
      key: value
    content: string            # script 内联内容

# 内容控制
pagefind: boolean              # 是否被搜索索引（默认 true）
draft: boolean                 # 草稿（生产构建跳过）
---

内置组件 props ​

所有组件从 @astrojs/starlight/components 引入。

Aside ​

Prop类型默认作用
type'note' | 'tip' | 'caution' | 'danger''note'变体
titlestring按类型默认自定义标题
iconIconName按类型默认自定义图标

Card ​

Prop类型必填作用
titlestring✅卡片标题
iconIconName❌图标

CardGrid ​

Prop类型默认作用
staggerbooleanfalse错落排版

LinkCard ​

Prop类型必填作用
titlestring✅标题
hrefstring✅链接地址
descriptionstring❌描述

LinkButton ​

Prop类型默认作用
hrefstring-链接
variant'primary' | 'secondary' | 'minimal''primary'按钮样式
iconIconName-图标
iconPlacement'start' | 'end''end'图标位置

Tabs ​

Prop类型作用
syncKeystring跨页面同步 key（相同 key 的 Tabs 同步选择）

TabItem ​

Prop类型必填作用
labelstring✅标签页文字
iconIconName❌标签页图标

Steps ​

无 props，包裹 <ol> 即可。

Badge ​

Prop类型默认作用
textstring-文字（必填）
variant'note' | 'tip' | 'success' | 'caution' | 'danger' | 'default''default'变体
size'small' | 'medium' | 'large''small'尺寸

Icon ​

Prop类型默认作用
nameIconName-图标名（必填）
labelstring-无障碍标签
sizestring'1em'CSS 尺寸
colorstring-CSS color
classstring-自定义类

FileTree ​

无 props，内部用嵌套 markdown 列表表达目录结构。

Code（Expressive Code 包装） ​

Prop类型作用
codestring代码字符串
langstring语言
titlestring顶部文件名
frame'code' | 'terminal' | 'none'外框
metastringExpressive Code meta（如 {1,3-5} 高亮）
markstring | string[]高亮
insstring | string[]标记新增
delstring | string[]标记删除
wrapboolean自动换行

Expressive Code 元信息 ​

代码块语言后追加，控制渲染：

语法含义
js {1,3-5}高亮第 1、3-5 行
js ins={2}第 2 行标记为新增（绿色 +）
js del={3}第 3 行标记为删除（红色 -）
js "keyword"高亮关键词
js title="hello.js"顶部显示文件名
bash frame="terminal"终端样式
js frame="none"无外框
js wrap长行自动换行
js {1-3} ins={4}多个组合

CSS 自定义属性 ​

颜色变量 ​

变量作用
--sl-color-accent主品牌色
--sl-color-accent-low浅 accent（背景用）
--sl-color-accent-high深 accent（深色背景上的文字）
--sl-color-white文字主色
--sl-color-gray-1 ~ --sl-color-gray-7灰度阶
--sl-color-black背景主色
--sl-color-bg主背景
--sl-color-bg-nav顶部导航背景
--sl-color-bg-sidebar侧边栏背景
--sl-color-bg-inline-code行内代码背景
--sl-color-text正文文字
--sl-color-text-accentaccent 文字
--sl-color-text-invert反向文字
--sl-color-hairline分隔线
--sl-color-hairline-shade阴影分隔线
--sl-color-hairline-light浅分隔线
--sl-color-asides-text-accentAside accent 文字
--sl-color-asides-border-{note/tip/caution/danger}Aside 边框
--sl-color-asides-bg-{note/tip/caution/danger}Aside 背景

暗色模式同名变量在 [data-theme='dark'] 选择器下重新定义。

字体变量 ​

变量作用
--sl-font正文字体栈
--sl-font-mono等宽字体栈

布局变量 ​

变量作用
--sl-content-width主内容最大宽度
--sl-content-pad-x内容左右内边距
--sl-sidebar-width侧边栏宽度
--sl-sidebar-pad-x侧边栏内边距
--sl-nav-height顶部导航高度
--sl-nav-pad-x顶部导航内边距
--sl-mobile-toc-height移动 TOC 高度

字号变量 ​

变量默认作用
--sl-text-xs0.8125remextra small
--sl-text-sm0.875remsmall
--sl-text-base1rembase
--sl-text-lg1.125remlarge
--sl-text-xl1.25remextra large
--sl-text-2xl1.5rem2x large
--sl-text-3xl1.875rem3x large
--sl-text-4xl2.25rem4x large
--sl-text-5xl3rem5x large
--sl-text-h1 ~ --sl-text-h5-标题字号
--sl-text-code-代码字号
--sl-text-code-sm-小代码字号

完整 props.css 列表：https://github.com/withastro/starlight/blob/main/packages/starlight/style/props.css

可覆盖组件清单 ​

components 字段可以替换的所有组件：

组件默认行为
Head渲染 <head> 元素内容（meta / link / script）
ThemeProvider主题切换的内联脚本
组件默认行为
Header顶部导航整体
SiteTitle站点标题 + logo
Search搜索按钮 / 搜索框
SocialIcons社交图标组
ThemeSelect主题切换器（明 / 暗 / 自动）
LanguageSelect语言切换器

Layout ​

组件默认行为
PageFrame整体页面框架（header + sidebar + content）
MobileMenuToggle移动端 sidebar 折叠按钮
Sidebar全局侧边栏 / 移动 dropdown
MobileMenuFooter移动端菜单页脚

Page Content ​

组件默认行为
TwoColumnContent主内容 + 右侧栏的两列布局
PageSidebar右侧 TOC 区域
TableOfContents桌面端 TOC
MobileTableOfContents移动端 TOC dropdown

Sections ​

组件默认行为
Banner页面顶部公告横幅
ContentPanel主内容包装
PageTitle页面 h1 标题
HeroHero 区域（splash 模板用）
MarkdownContentMarkdown 内容包装
DraftContentNotice草稿提示
FallbackContentNotice缺失翻译提示
组件默认行为
Footer页面页脚整体
LastUpdated最后更新日期
EditLink编辑链接
Pagination上一页 / 下一页导航

Accessibility ​

组件默认行为
SkipLink跳到主内容（键盘无障碍）

包装默认组件示例 ​

astro
---
import Default from '@astrojs/starlight/components/SocialIcons.astro';
---

<a href="mailto:hello@example.com">Email</a>

<Default><slot /></Default>

<slot /> 必须保留以转发 children；带命名 slot 的组件（如 PageFrame）也要把所有 named slot 全部转发。

Route Data API ​

starlightRoute 对象 ​

通过 Astro.locals.starlightRoute 在 .astro 组件 / route middleware 里访问：

ts
interface StarlightRouteData {
  // 标识
  id: string;                    // 页面 slug
  entry: ContentEntry;           // Content collection entry 完整对象
  isFallback: boolean;           // 是否为 fallback 内容

  // 语言
  locale: string | undefined;    // 当前语言（root locale 时为 undefined）
  lang: string;                  // BCP-47 lang code（如 'en' / 'zh-CN'）
  dir: 'ltr' | 'rtl';            // 文字方向

  // 导航
  sidebar: SidebarItem[];        // 当前页的 sidebar 结构
  hasSidebar: boolean;
  pagination: {
    prev?: { link: string; label: string } | undefined;
    next?: { link: string; label: string } | undefined;
  };

  // 内容
  headings: Array<{ depth: number; slug: string; text: string }>;
  toc: { items: TocItem[] };
  lastUpdated: Date | undefined;

  // 站点
  siteTitle: string;
  siteTitleHref: string;
  editUrl: URL | undefined;
}

defineRouteMiddleware() 定义中间件 ​

ts
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';

export const onRequest = defineRouteMiddleware(async (context, next) => {
  // 修改 route data
  const data = context.locals.starlightRoute;
  data.entry.data.title = data.entry.data.title + ' (Beta)';

  // 调用下一个 middleware（可选）
  return next();
});

StarlightPage 组件 ​

让非 src/content/docs/ 路由也用 Starlight 布局：

astro
---
// src/pages/dashboard.astro
import { StarlightPage } from '@astrojs/starlight/components';
---

<StarlightPage
  frontmatter={{
    title: 'Dashboard',
    template: 'doc',
    pagefind: false,
  }}
  hasSidebar={false}
>
  <h2>非文档页内容</h2>
</StarlightPage>

Plugin API ​

Plugin 形状 ​

ts
interface StarlightPlugin {
  name: string;
  hooks: {
    'config:setup'?: (options: ConfigSetupOptions) => void | Promise<void>;
    'i18n:setup'?: (options: I18nSetupOptions) => void | Promise<void>;
  };
}

config:setup Hook ​

参数：

ts
interface ConfigSetupOptions {
  config: StarlightUserConfig;        // 用户的 Starlight 配置
  updateConfig: (config: Partial<StarlightUserConfig>) => void;
  addIntegration: (integration: AstroIntegration) => void;
  addRouteMiddleware: (options: {
    entrypoint: string;
    order?: 'pre' | 'post' | 'default';
  }) => void;
  astroConfig: AstroConfig;
  command: 'dev' | 'build' | 'preview';
  logger: AstroIntegrationLogger;
  useTranslations: (lang: string) => (key: string) => string;
  absolutePathToLang: (path: string) => string;
}

i18n:setup Hook ​

参数：

ts
interface I18nSetupOptions {
  injectTranslations: (translations: Record<string, Record<string, string>>) => void;
}

注入翻译示例：

ts
hooks: {
  'i18n:setup'({ injectTranslations }) {
    injectTranslations({
      en: {
        'myPlugin.label': 'My Plugin',
      },
      'zh-CN': {
        'myPlugin.label': '我的插件',
      },
    });
  },
}

Plugin 完整示例 ​

ts
// src/plugins/my-plugin.ts
import type { StarlightPlugin } from '@astrojs/starlight/types';

export default function myPlugin(): StarlightPlugin {
  return {
    name: 'starlight-my-plugin',
    hooks: {
      'config:setup'({ updateConfig, addIntegration, logger }) {
        logger.info('My Plugin loaded!');

        updateConfig({
          customCss: ['./src/plugins/my-plugin.css'],
        });
      },
      'i18n:setup'({ injectTranslations }) {
        injectTranslations({
          en: { 'myPlugin.hello': 'Hello' },
          'zh-CN': { 'myPlugin.hello': '你好' },
        });
      },
    },
  };
}

astro.config.mjs 使用：

js
import starlight from '@astrojs/starlight';
import myPlugin from './src/plugins/my-plugin.ts';

export default defineConfig({
  integrations: [
    starlight({
      title: '...',
      plugins: [myPlugin()],
    }),
  ],
});

社区 Plugin 速查 ​

Plugin作用安装包
starlight-blog博客系统（含 RSS / 作者 / 标签）starlight-blog
starlight-openapiOpenAPI / Swagger 自动生成 API 文档starlight-openapi
starlight-image-zoom图片点击放大starlight-image-zoom
starlight-versions多版本文档（对标 Docusaurus）starlight-versions
starlight-sidebar-topics多 sidebar 主题（文档 + API + 教程分离）starlight-sidebar-topics
starlight-links-validator死链检测starlight-links-validator
starlight-typedoc从 TypeScript 源码自动生成 APIstarlight-typedoc
starlight-llms-txtllms.txt 标准支持starlight-llms-txt
starlight-obsidianObsidian vault 发布starlight-obsidian
starlight-videos视频教程集成starlight-videos
starlight-heading-badges标题徽章starlight-heading-badges
starlight-auto-sidebar自动 sidebar 增强starlight-auto-sidebar
starlight-scroll-to-top滚动到顶部按钮starlight-scroll-to-top
starlight-tags标签分类系统starlight-tags
starlight-telescopeFuzzy 搜索（键盘优先）starlight-telescope
@astrojs/starlight-docsearchAlgolia DocSearch 替换 Pagefind@astrojs/starlight-docsearch
@astrojs/starlight-tailwindTailwind v4 集成@astrojs/starlight-tailwind
@astrojs/starlight-markdocMarkdoc 预设@astrojs/starlight-markdoc

完整列表见 Starlight Plugins Showcase。

内置图标参考 ​

通过 <Icon name="..." /> 使用，常用图标分类：

UI 控件 ​

right-arrow  left-arrow  up-arrow  down-arrow
right-caret  left-caret  up-caret  down-caret
close  bars  setting  search  pen  trash  external
add  subtract  list-format  comment-alt  bookmark

状态 / 反馈 ​

approve-check  approve-check-circle  error  warning
information  question  pencil  star  heart  flag

操作 ​

download  upload  cloud-download  cloud-upload  rocket
copy  open-book  document  laptop  puzzle  random

品牌（社交） ​

github  gitlab  gitea  codeberg  bitbucket  forgejo
discord  mastodon  bluesky  x.com  twitter  threads
youtube  twitch  instagram  facebook  linkedin
patreon  ko-fi  buy-me-a-coffee  email  rss

技术品牌 ​

node  astro  react  vue  svelte  solid  preact
typescript  javascript  python  rust  go  java
docker  kubernetes  git  npm  pnpm  yarn  bun

文件类型（seti: 前缀） ​

seti:typescript  seti:react  seti:vue  seti:svelte
seti:python  seti:rust  seti:go  seti:json  seti:yaml
seti:markdown  seti:html  seti:css  seti:scss  seti:image
seti:default  seti:config  seti:lock  seti:font  seti:db
seti:lua  seti:php  seti:ruby  seti:swift  seti:kotlin

完整可点击列表（含搜索）：https://starlight.astro.build/reference/icons/

翻译 key 速查 ​

src/content/i18n/{locale}.json 里可重写的常见 UI key：

Key默认（英文）
skipLink.labelSkip to content
search.labelSearch
search.shortcutLabel(Press / to Search)
search.cancelLabelCancel
search.devWarningSearch is only available in production builds.
themeSelect.accessibleLabelSelect theme
themeSelect.darkDark
themeSelect.lightLight
themeSelect.autoAuto
languageSelect.accessibleLabelSelect language
menuButton.accessibleLabelMenu
sidebarNav.accessibleLabelMain
tableOfContents.onThisPageOn this page
tableOfContents.overviewOverview
i18n.untranslatedContentThis content is not available in your language yet.
page.editLinkEdit page
page.lastUpdatedLast updated:
page.previousLinkPrevious
page.nextLinkNext
page.draftThis content is a draft and will not be included in production builds.
404.textPage not found.
aside.noteNote
aside.tipTip
aside.cautionCaution
aside.dangerDanger

完整 key 列表见 @astrojs/starlight/translations 源码。

配置最小化示例 ​

最简 astro.config.mjs：

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
    }),
  ],
});

最简 src/content.config.ts：

ts
import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
};

src/content/docs/index.md：

md
---
title: 欢迎
---

# 你好，Starlight!

配置完整示例 ​

下面是一个生产级别的完整 astro.config.mjs：

js
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import starlightImageZoom from 'starlight-image-zoom';
import starlightLinksValidator from 'starlight-links-validator';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://mydocs.example.com',
  trailingSlash: 'always',

  integrations: [
    starlight({
      title: {
        en: 'My Docs',
        'zh-cn': '我的文档',
      },
      description: 'My amazing documentation',

      defaultLocale: 'en',
      locales: {
        en: { label: 'English', lang: 'en' },
        'zh-cn': { label: '简体中文', lang: 'zh-CN' },
      },

      logo: {
        light: './src/assets/logo-light.svg',
        dark: './src/assets/logo-dark.svg',
        alt: 'My Docs',
      },

      favicon: '/favicon.svg',

      social: [
        { label: 'GitHub', icon: 'github', href: 'https://github.com/me/myproject' },
        { label: 'Discord', icon: 'discord', href: 'https://discord.gg/myproject' },
      ],

      editLink: {
        baseUrl: 'https://github.com/me/myproject/edit/main/',
      },

      lastUpdated: true,

      sidebar: [
        {
          label: '入门',
          autogenerate: { directory: 'getting-started' },
        },
        {
          label: '指南',
          collapsed: false,
          items: [
            { label: '介绍', slug: 'guides/intro' },
            {
              label: '安装',
              items: [
                { label: 'macOS', slug: 'guides/install/macos' },
                { label: 'Linux', slug: 'guides/install/linux' },
                { label: 'Windows', slug: 'guides/install/windows' },
              ],
            },
            {
              label: '进阶',
              autogenerate: { directory: 'guides/advanced', collapsed: true },
            },
          ],
        },
        {
          label: '参考',
          autogenerate: { directory: 'reference', collapsed: true },
        },
        {
          label: '社区',
          items: [
            { label: 'GitHub', link: 'https://github.com/me/myproject' },
            { label: '更新日志', slug: 'changelog' },
          ],
        },
      ],

      customCss: [
        './src/styles/custom.css',
        '@fontsource/inter/400.css',
        '@fontsource/inter/600.css',
      ],

      pagefind: {
        ranking: {
          pageLength: 0.5,
          termFrequency: 0.7,
        },
      },

      expressiveCode: {
        themes: ['github-light', 'github-dark'],
      },

      tableOfContents: {
        minHeadingLevel: 2,
        maxHeadingLevel: 4,
      },

      components: {
        Footer: './src/components/MyFooter.astro',
      },

      plugins: [
        starlightImageZoom(),
        starlightLinksValidator(),
      ],
    }),

    sitemap(),
  ],
});

文件约定速查 ​

路径作用
astro.config.mjsAstro + Starlight 主配置
src/content.config.tsContent Collections 配置
src/content/docs/**/*.{md,mdx,mdoc}文档内容
src/content/docs/index.md站点首页
src/content/docs/404.md自定义 404 页
src/content/i18n/{locale}.{json,yml}UI 翻译
src/assets/**Vite 处理的资源（图片 / 字体）
src/components/**.astro自定义 Astro 组件（用于 components 覆盖）
src/styles/**.css自定义 CSS（用 customCss 注入）
public/**静态资源直传（不处理）
public/favicon.svgfavicon 默认位置
src/pages/**.{astro,ts,js}非 Starlight 路由（custom pages / API endpoints）
src/env.d.tsTypeScript 环境类型（Astro 自动生成）

学习资源 ​

资源链接
官方文档https://starlight.astro.build/
配置参考https://starlight.astro.build/reference/configuration/
Frontmatterhttps://starlight.astro.build/reference/frontmatter/
Plugins 资源https://starlight.astro.build/resources/plugins/
Showcase 案例https://starlight.astro.build/resources/showcase/
GitHub 仓库https://github.com/withastro/starlight
Astro 文档https://docs.astro.build/
Expressive Codehttps://expressive-code.com/
Pagefindhttps://pagefind.app/
Markdochttps://markdoc.dev/
Discordhttps://astro.build/chat