配置参考

配置 `starlight` 集成

Starlight 是在 Astro web 框架之上构建的集成。你可以在 astro.config.mjs 配置文件中配置你的项目：

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

export default defineConfig({
  integrations: [
    starlight({
      title: '我的令人愉快的文档网站',
    }),
  ],
});

你可以将以下选项传递给 starlight 集成。

`title` (必填)

类型： string | Record<string, string>

设置你的网站标题。将用于元数据和浏览器标签标题。

这个值可以是一个字符串，或者对于多语言网站，可以是一个包含每种不同语言值的对象。当使用对象形式时，键必须是 BCP-47 标签（例如 en，ar 或 zh-CN）：

starlight({
  title: {
    en: 'My delightful docs site',
    de: 'Meine bezaubernde Dokumentationsseite',
  },
});

`description`

类型： string

设置你的网站描述。如果页面的 frontmatter 中没有设置 description，则在 <meta name="description"> 标签中与搜索引擎共享元数据。

`logo`

类型： LogoConfig

在导航栏中设置一个 logo 图片，与网站标题一起显示或替代网站标题。你可以设置单个 src 属性，也可以为 light 和 dark 设置单独的图像源。

starlight({
  logo: {
    src: './src/assets/my-logo.svg',
  },
});

`LogoConfig`

type LogoConfig = { alt?: string; replacesTitle?: boolean } & (
  | { src: string }
  | { light: string; dark: string }
);

`tableOfContents`

类型： false | { minHeadingLevel?: number; maxHeadingLevel?: number; }
默认值： { minHeadingLevel: 2, maxHeadingLevel: 3 }

配置每个页面右侧显示的目录。默认情况下，<h2> 和 <h3> 标题将包含在此目录中。

`editLink`

类型： { baseUrl: string }

通过设置你要使用的 base URL 来启用 “编辑此页” 链接。最终链接将是 editLink.baseUrl + 当前页面路径。例如，要启用在 GitHub 上编辑 withastro/starlight 仓库中的页面：

starlight({
  editLink: {
    baseUrl: 'https://github.com/withastro/starlight/edit/main/',
  },
});

使用此配置，/introduction 页面将具有指向 https://github.com/withastro/starlight/edit/main/src/content/docs/introduction.md 的编辑链接。

`sidebar`

类型： SidebarItem[]

配置你的网站的侧边栏导航项目。

侧边栏是一个由链接、链接组和自动生成条目组成的数组。侧边栏条目通过以下属性之一来定义：

link — 指向特定 URL 的单个链接，例如 '/home' 或 'https://example.com'。链接还必须具有 label。
slug — 指向一个内部页面的引用，例如 'guides/getting-started'。链接页面的标题将默认用作标签。
items — 包含更多侧边栏链接、子组和自动生成条目的数组。分组还必须具有 label。
autogenerate — 一个用于指定文档目录以自动生成链接和子组的对象。自动生成的条目可以放置在分组的 items 数组中。

内部链接也可以被指定为字符串，而不是带有 slug 属性的对象。

starlight({
  sidebar: [
    // 标记为“Home”的单个链接项。
    { label: 'Home', link: '/' },
    // 一个标记为“Start Here”的组，其中包含四个链接。
    {
      label: 'Start Here',
      items: [
        // 在内部链接中使用 `slug`。
        { slug: 'intro' },
        { slug: 'installation' },
        // 或者使用内部链接的简易写法。
        'tutorial',
        'next-steps',
      ],
    },
    // 一个链接到参考目录中所有页面的组。
    {
      label: 'Reference',
      items: [{ autogenerate: { directory: 'reference' } }],
    },
  ],
});

排序

自动生成的侧边栏组按文档名字母顺序排序。例如，从 astro.md 生成的页面将显示在 starlight.md页面上方。

折叠组

默认情况下，链接组是展开的。你可以通过将组的 collapsed 属性设置为 true 来更改此行为。

自动生成的子组默认也是展开的。设置 autogenerate.collapsed 属性以折叠它们。

sidebar: [
  // 一个折叠的链接组。
  {
    label: 'Collapsed Links',
    collapsed: true,
    items: ['intro', 'next-steps'],
  },
  // 一个展开的组，其中包含折叠的自动生成的子组。
  {
    label: 'Reference',
    items: [
      {
        autogenerate: {
          directory: 'reference',
          collapsed: true,
        },
      },
    ],
  },
],

翻译标签

如果你的网站是多语言的，每个项目的 label 被认为是默认语言。你可以设置一个 translations 属性来为你支持的其他语言提供标签：

sidebar: [
  // 一个侧边栏示例，其中的标签被翻译成简体中文。
  {
    label: 'Start Here',
    translations: { 'zh-CN': '从这里开始' },
    items: [
      {
        label: 'Getting Started',
        translations: { 'zh-CN': '开始使用' },
        link: '/getting-started',
      },
      {
        label: 'Project Structure',
        translations: { 'zh-CN': '项目结构' },
        link: '/structure',
      },
    ],
  },
],

`SidebarItem`

type SidebarItem =
  | string
  | ({
      translations?: Record<string, string>;
      badge?: string | BadgeConfig;
    } & (
      | {
          // 链接
          link: string;
          label: string;
          attrs?: Record<string, string | number | boolean | undefined>;
        }
      | {
          // 内部链接
          slug: string;
          label?: string;
          attrs?: Record<string, string | number | boolean | undefined>;
        }
      | {
          // 链接组
          label: string;
          items: SidebarItem[];
          collapsed?: boolean;
        }
    ))
  | {
      // 自动生成的链接和子组
      autogenerate: {
        directory: string;
        collapsed?: boolean;
        attrs?: Record<string, string | number | boolean | undefined>;
      };
    };

`BadgeConfig`

interface BadgeConfig {
  text: string;
  variant?: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default';
  class?: string;
}

`locales`

类型： { [dir: string]: LocaleConfig }

为你的网站设置支持的 locales 来配置国际化（i18n）。

每个条目都应该使用该语言文件保存的目录作为 key。

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Site',
      // 为这个网站设置英语作为默认语言。
      defaultLocale: 'en',
      locales: {
        // 英文文档在 `src/content/docs/en/`
        en: {
          label: 'English',
        },
        // 简体中文文档在 `src/content/docs/zh-cn/`
        'zh-cn': {
          label: '简体中文',
          lang: 'zh-CN',
        },
        // 阿拉伯文档在 `src/content/docs/ar/`
        ar: {
          label: 'العربية',
          dir: 'rtl',
        },
      },
    }),
  ],
});

`LocaleConfig`

interface LocaleConfig {
  label: string;
  lang?: string;
  dir?: 'ltr' | 'rtl';
}

你可以为每个语言设置以下选项：

`label` (必填)

类型： string

要向用户显示的此语言的标签，例如在语言切换器中。大多数情况下，你会希望这是该语言的名称，因为该语言的用户希望阅读它，例如"English"，"العربية"，或者 "简体中文"。

`lang`

类型： string

此语言的 BCP-47 标签，例如"en"，"ar"，或者 "zh-CN"。如果未设置，则默认使用该语言的目录名称。如果没有找到特定于区域的翻译，带有区域子标签的语言标签（例如pt-BR或en-US）将使用内置的 UI 翻译作为其基本语言。

`dir`

类型： 'ltr' | 'rtl'

这种语言的写作方向；"ltr" 表示从左到右（默认值）或 "rtl" 表示从右到左。

root locale

你可以通过设置 root locale 来提供不带 /lang/ 目录的默认语言：

starlight({
  locales: {
    root: {
      label: 'English',
      lang: 'en',
    },
    fr: {
      label: 'Français',
    },
  },
});

举例，这允许你将 /getting-started/ 作为英语路由提供，并将 /fr/getting-started/ 作为等效的法语页面。

`defaultLocale`

类型： string

设置此站点的默认语言。该值应该与你的 locales 对象的键之一匹配。（如果你的默认语言是你的root locale，你可以跳过这一步。）

默认语言将用于在缺少翻译时提供回退内容。

`social`

类型： Array<{ label: string; icon: StarlightIcon; href: string }>

可选的社交媒体账户详情。每个条目将显示为网站 header 中的图标链接。

starlight({
  social: [
    { icon: 'codeberg', label: 'Codeberg', href: 'https://codeberg.org/knut' },
    { icon: 'discord', label: 'Discord', href: 'https://astro.build/chat' },
    { icon: 'github', label: 'GitHub', href: 'https://github.com/withastro' },
    { icon: 'gitlab', label: 'GitLab', href: 'https://gitlab.com/delucis' },
    { icon: 'mastodon', label: 'Mastodon', href: 'https://m.webtoo.ls/@astro' },
  ],
});

`customCss`

类型： string[]

提供 CSS 文件来自定义你的 Starlight 网站的外观和风格。

支持相对于项目根目录的本地 CSS 文件，例如 './src/custom.css'，以及你安装为 npm 模块的 CSS，例如 '@fontsource/roboto'。

starlight({
  customCss: ['./src/custom-styles.css', '@fontsource/roboto'],
});

`markdown`

类型： { headingLinks?: boolean; processedDirs?: string[] }
默认值： { headingLinks: true, processedDirs: [] }

配置 Starlight 的 Markdown 处理。

`headingLinks`

类型： boolean
默认值： true

控制标题是否渲染为可点击的锚点链接。

starlight({
  markdown: {
    // 禁用 Starlight 的可点击标题锚点链接。
    headingLinks: false,
  },
}),

`processedDirs`

类型： string[]
默认值： []

定义应该由 Starlight 的 Markdown 管道处理文件的额外目录。默认情况下，仅处理使用 Starlight 的 docsLoader() 加载的 Markdown 和 MDX 内容。支持相对于项目根目录的本地目录，例如 './src/data/comments/'。

Starlight 的处理内容包括对可点击标题锚点链接、旁白 Markdown 指令语法以及代码块的 RTL 支持。如果你正在通过 <StarlightPage> 组件在自定义页面中通过自定义内容集合渲染内容，并希望 Starlight 的 Markdown 处理也应用于该内容，那么这个选项非常有用。

starlight({
  markdown: {
    // 处理位于 `src/data/reviews/` 目录中 `reviews` 内容集合的 Markdown 文件。
    processedDirs: ['./src/data/reviews/'],
  },
}),

`expressiveCode`

类型： StarlightExpressiveCodeOptions | boolean
默认值： true

Starlight 使用 Expressive Code 来渲染代码块，并添加对代码示例的高亮支持，向代码块添加文件名等。请参阅 “代码块”指南以了解如何在你的 Markdown 和 MDX 内容中使用 Expressive Code 语法。

你可以通过在 Starlight 的 expressiveCode 选项中设置任何标准的 Expressive Code 配置选项以及一些特定于 Starlight 的属性。比如，设置 Expressive Code 的 styleOverrides 选项来覆盖默认的 CSS。这样就可以自定义代码块，比如给你的代码块添加圆角：

starlight({
  expressiveCode: {
    styleOverrides: { borderRadius: '0.5rem' },
  },
});

如果你想禁用 Expressive Code，请在 Starlight 配置中设置 expressiveCode: false：

starlight({
  expressiveCode: false,
});

除了标准的 Expressive Code 选项之外，你还可以在 expressiveCode 配置中设置以下 Starlight 特定属性，以进一步自定义代码块的主题行为：

`themes`

类型： Array<string | ThemeObject | ExpressiveCodeTheme>
默认值： ['starlight-dark', 'starlight-light']

设置用于代码块样式的主题。有关支持的主题格式的详细信息，请参阅 Expressive Code themes 文档。

Starlight 默认使用 Sarah Drasner 的 Night Owl 主题的深色和浅色变体。

如果你提供至少一个深色和一个浅色主题，Starlight 将自动将活动代码块主题与当前网站主题保持同步。使用 useStarlightDarkModeSwitch 选项配置此行为。

`useStarlightDarkModeSwitch`

类型： boolean
默认值： true

当设置为 true 时，代码块会在网站主题更改时自动在浅色和深色主题之间切换。当设置为 false 时，你必须手动添加 CSS 来处理多个主题之间的切换。

`useStarlightUiThemeColors`

类型： boolean
默认值： 如果未设置 themes，则为 true，否则为 false

当设置为 true 时，Starlight 的 CSS 变量用于代码块 UI 元素的颜色（背景、按钮、阴影等），与网站颜色主题相匹配。当设置为 false 时，这些元素使用活动语法高亮主题提供的颜色。

`pagefind`

类型： boolean | PagefindOptions
默认值： true

配置 Starlight 的默认站点搜索 provider Pagefind。

将其设置为 false 以禁用使用 Pagefind 索引你的网站。这也将隐藏默认的搜索 UI。

当 prerender 选项设置为 false 时，无法启用 Pagefind。

将 pagefind 设置为对象，以配置 Pagefind 搜索客户端。

查看 Pagefind 文档中的 “自定义 Pagefind 的结果排序”，了解如何使用 pagefind.ranking 选项来控制搜索结果排序的计算。
查看 Pagefind 文档中的 “搜索多个站点”，了解如何使用 pagefind.mergeIndex 选项来控制如何跨多个站点搜索。

`PagefindOptions`

interface PagefindOptions {
  ranking?: PagefindRankingOptions;
  indexWeight?: number;
  mergeIndex?: Array<{
    bundlePath: string;
    indexWeight?: number;
    basePath?: string;
    baseUrl?: string;
    mergeFilter?: Record<string, string | string[]>;
    language?: string;
    ranking?: PagefindRankingOptions;
  }>;
}

interface PagefindRankingOptions {
  pageLength?: number;
  termFrequency?: number;
  termSaturation?: number;
  termSimilarity?: number;
  diacriticSimilarity?: number;
  metaWeights?: Record<string, number>;
}

`prerender`

类型： boolean
默认值： true

定义 Starlight 页面是应预渲染为静态 HTML 还是由 SSR 适配器按需渲染。

默认情况下，Starlight 页面是预渲染的。如果你正在使用 SSR 适配器并希望按需渲染 Starlight 页面，请设置为 prerender: false。

`head`

类型： HeadConfig[]

添加自定义标签到你的 Starlight 网站的 <head> 中。可以用于添加分析和其他第三方脚本和资源。

starlight({
  head: [
    // 示例：添加 Fathom 分析脚本标签。
    {
      tag: 'script',
      attrs: {
        src: 'https://cdn.usefathom.com/script.js',
        'data-site': 'MY-FATHOM-ID',
        defer: true,
      },
    },
  ],
});

在 head 中的条目会直接转换为 HTML 元素，并不会经过 Astro 的脚本或样式处理。如果你需要导入本地资源，如脚本、样式或图片，请重写 Head 组件。

`HeadConfig`

interface HeadConfig {
  tag: string;
  attrs?: Record<string, string | boolean | undefined>;
  content?: string;
}

`lastUpdated`

类型： boolean
默认值： false

控制页脚是否显示页面上次更新的时间。

默认情况下，此功能依赖于你的存储库的 Git 历史记录，并且在某些执行浅克隆的部署平台上可能不准确。页面可以使用 lastUpdated frontmatter 字段覆盖此设置或基于 Git 的日期。

`pagination`

类型： boolean
默认值： true

页面可以使用 prev 和 next frontmatter 字段覆盖此设置或链接文本和/或 URL。

`favicon`

类型： string
默认值： '/favicon.svg'

设置网站的默认 favicon 的路径，它应该位于 public/ 目录中，并且是一个有效的（.ico，.gif，.jpg，.png 或 .svg）图标文件。

starlight({
  favicon: '/images/favicon.svg',
}),

如果你需要设置其他变体或回退的 favicon，你可以使用 head 选项添加标签：

starlight({
  favicon: '/images/favicon.svg',
  head: [
    // 为 Safari 添加 ICO favicon 回退。
    {
      tag: 'link',
      attrs: {
        rel: 'icon',
        href: '/images/favicon.ico',
        sizes: '32x32',
      },
    },
  ],
});

`titleDelimiter`

类型： string
默认值： '|'

设置在页面的 <title> 标签里页面标题和网站标题之间的分隔符，它会显示在浏览器标签上。

默认情况下，每个页面的 <title> 都是 页面标题 | 网站标题。举例，本页面的标题是“配置参考”，本站点的标题是“Starlight”，所以本页面的 <title> 是“配置参考 | Starlight”。

`disable404Route`

类型： boolean
默认值： false

禁用注入 Starlight 的默认 404 页面。要在项目中使用自定义的 src/pages/404.astro 路由，请将此选项设置为 true。

`routeMiddleware`

类型： string | string[]

提供路由中间件的路径，可以修改 Starlight 处理数据的方式。这些文件路径不能与 Astro 的中间件冲突。

在路由数据指南中查看有关如何创建路由中间件的详细信息。

`components`

类型： Record<string, string>

提供组件的路径来覆盖 Starlight 的默认实现。

starlight({
  components: {
    SocialLinks: './src/components/MySocialLinks.astro',
  },
});

要查阅所有可覆盖的组件，请参阅覆盖参考。

`plugins`

类型： StarlightPlugin[]

使用自定义插件扩展 Starlight。插件将更改应用到你的项目中，以修改或添加 Starlight 的功能。

访问插件 showcase 查看可用插件列表。

starlight({
  plugins: [starlightPlugin()],
});

有关创建自己的插件的详细信息，请参阅插件参考。

`credits`

类型： boolean
默认值： false

启用在你的网站页脚显示 “基于 Starlight 构建” 的链接。

starlight({
  credits: true,
});

配置内容集合

Starlight 使用 Astro 内容集合来加载你的内容。 Starlight 的内容加载器和 schema 帮助按要求配置集合。

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

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  // 可选：i18n 集合用于在多语言站点中翻译 UI
  i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
};

加载器

Starlight 从 @astrojs/starlight/loaders 模块导出以下 Astro 加载器，以简化配置内容集合。

`docsLoader()`

docsLoader() 从 src/content/docs/ 目录加载本地的 Markdown、MDX 和 Markdoc 文件。以下划线 (_) 开头的文件名将被忽略。

导入

import { docsLoader } from '@astrojs/starlight/loaders';

选项

`generateId()`

类型： ({ entry: string; base: URL; data: Record<string, unknown> }) => string

默认情况下，使用 docsLoader() 生成的页面会通过一个 sluggifier 处理你的文件名，该工具会删除特殊字符并将文件名转换为小写。如果你想覆盖此默认行为，请提供你自己的自定义 generateId() 函数。

例如，这可以用于保留那些会被删除的特殊字符。默认情况下，Example.File.md 将位于 /examplefile。如果你希望它位于 /Example.File，可以通过定义一个自定义的 generateId() 函数来实现：

docsLoader({
  // 删除 `.md` 或 `.mdx` 扩展名，但不处理文件名。
  generateId: ({ entry }) => entry.split('.').slice(0, -1).join('.'),
}),

参阅 Astro 文档中的 generateId() 了解更多详情。

`i18nLoader()`

i18nLoader() 从 src/content/i18n/ 目录加载本地的 JSON 和 YAML 文件。以下划线 (_) 开头的文件名将被忽略。

导入

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

选项

当前没有可用于配置 i18nLoader() 的选项。

模式

Starlight 从 @astrojs/starlight/schema 模块提供以下内容集合 schema。这些 schema 必须用于 Starlight 依赖的 docs 和 i18n 集合。

`docsSchema()`

docsSchema() 解析 docs 集合中所有内容的 frontmatter。

导入

import { docsSchema } from '@astrojs/starlight/schema';

选项

`extend`

类型： Zod schema 或返回 Zod schema 的函数
默认值： z.object({})

使用额外的字段扩展 Starlight 的 frontmatter schema。参阅 “自定义 frontmatter schema” 了解更多使用 extend 选项的详细信息。

`i18nSchema()`

i18nSchema() 解析 i18n 集合中的所有数据文件。

导入

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

选项

`extend`

类型： Zod 对象
默认值： z.object({})

使用额外的字段扩展 Starlight 的 i18n schema。参阅 “扩展翻译 schema” 了解更多使用 extend 选项的详细信息。

配置参考

配置 starlight 集成

title (必填)

description

logo

LogoConfig

tableOfContents

editLink

sidebar

排序

折叠组

翻译标签

SidebarItem

BadgeConfig

locales

LocaleConfig

label (必填)

lang

dir

root locale

defaultLocale

social

customCss

markdown

headingLinks

processedDirs

expressiveCode

themes

useStarlightDarkModeSwitch

useStarlightUiThemeColors

pagefind

PagefindOptions

prerender

head

HeadConfig

lastUpdated

pagination

favicon

titleDelimiter

disable404Route

routeMiddleware

components

plugins

credits

配置内容集合

加载器

docsLoader()

导入

选项

generateId()

i18nLoader()

导入

选项

模式

docsSchema()

导入

选项

extend

i18nSchema()

导入

选项

extend

配置 `starlight` 集成

`title` (必填)

`description`

`logo`

`LogoConfig`

`tableOfContents`

`editLink`

`sidebar`

`SidebarItem`

`BadgeConfig`

`locales`

`LocaleConfig`

`label` (必填)

`lang`

`dir`

`defaultLocale`

`social`

`customCss`

`markdown`

`headingLinks`

`processedDirs`

`expressiveCode`

`themes`

`useStarlightDarkModeSwitch`

`useStarlightUiThemeColors`

`pagefind`

`PagefindOptions`

`prerender`

`head`

`HeadConfig`

`lastUpdated`

`pagination`

`favicon`

`titleDelimiter`

`disable404Route`

`routeMiddleware`

`components`

`plugins`

`credits`

`docsLoader()`

`generateId()`

`i18nLoader()`

`docsSchema()`

`extend`

`i18nSchema()`

`extend`