跳转到内容

配置参考

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

astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
integrations: [
starlight({
title: 'My delightful docs site',
}),
],
});

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

类型:string | Record<string, string>

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

该值可以是一个字符串,或者对于多语言站点,可以是一个为每个不同语言环境提供值的对象。当使用对象形式时,键必须是 BCP-47 标签(例如 enarzh-CN)。

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

类型: string

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

类型:LogoConfig

设置一个 logo 图像,以在导航栏中与网站标题一起显示或替代网站标题。你可以设置一个单独的 src 属性,或者为 lightdark 模式设置不同的图像源。

starlight({
logo: {
src: './src/assets/my-logo.svg',
},
});
type LogoConfig = { alt?: string; replacesTitle?: boolean } & (
| { src: string }
| { light: string; dark: string }
);

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

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

类型:{ baseUrl: string }

通过设置基础 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

类型:SidebarItem[]

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

侧边栏是一个由链接和链接组构成的数组。除了使用 slug 的项目外,每个项目都必须有一个 label 和以下属性之一:

  • link — 指向特定 URL 的单个链接,例如 '/home''https://example.com'

  • slug — 指向内部页面的引用,例如 'guides/getting-started'

  • items — 包含更多侧边栏链接和子组的数组。

  • autogenerate — 一个指定文档目录的对象,用于自动生成一组链接。

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

starlight({
sidebar: [
// A single link item labelled “Home”.
{ label: 'Home', link: '/' },
// A group labelled “Start Here” containing four links.
{
label: 'Start Here',
items: [
// Using `slug` for internal links.
{ slug: 'intro' },
{ slug: 'installation' },
// Or using the shorthand for internal links.
'tutorial',
'next-steps',
],
},
// A group linking to all pages in the reference directory.
{
label: 'Reference',
autogenerate: { directory: 'reference' },
},
],
});

自动生成的侧边栏组按文件名的字母顺序排序。例如,从 astro.md 生成的页面将出现在 starlight.md 的页面之上。

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

自动生成的子组默认遵循其父组的 collapsed 属性。设置 autogenerate.collapsed 属性可以覆盖此行为。

sidebar: [
// A collapsed group of links.
{
label: 'Collapsed Links',
collapsed: true,
items: ['intro', 'next-steps'],
},
// An expanded group containing collapsed autogenerated subgroups.
{
label: 'Reference',
autogenerate: {
directory: 'reference',
collapsed: true,
},
},
],

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

sidebar: [
// An example sidebar with labels translated to Brazilian Portuguese.
{
label: 'Start Here',
translations: { 'pt-BR': 'Comece Aqui' },
items: [
{
label: 'Getting Started',
translations: { 'pt-BR': 'Introdução' },
link: '/getting-started',
},
{
label: 'Project Structure',
translations: { 'pt-BR': 'Estrutura de Projetos' },
link: '/structure',
},
],
},
],
type SidebarItem =
| string
| ({
translations?: Record<string, string>;
badge?: string | BadgeConfig;
} & (
| {
// Link
link: string;
label: string;
attrs?: Record<string, string | number | boolean | undefined>;
}
| {
// Internal link
slug: string;
label?: string;
attrs?: Record<string, string | number | boolean | undefined>;
}
| {
// Group of links
label: string;
items: SidebarItem[];
collapsed?: boolean;
}
| {
// Autogenerated link group
label: string;
autogenerate: {
directory: string;
collapsed?: boolean;
attrs?: Record<string, string | number | boolean | undefined>;
};
collapsed?: boolean;
}
));
interface BadgeConfig {
text: string;
variant?: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default';
class?: string;
}

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

通过设置支持的 locales 来为你的网站配置国际化 (i18n)

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

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
integrations: [
starlight({
title: 'My Site',
// Set English as the default language for this site.
defaultLocale: 'en',
locales: {
// English docs in `src/content/docs/en/`
en: {
label: 'English',
},
// Simplified Chinese docs in `src/content/docs/zh-cn/`
'zh-cn': {
label: '简体中文',
lang: 'zh-CN',
},
// Arabic docs in `src/content/docs/ar/`
ar: {
label: 'العربية',
dir: 'rtl',
},
},
}),
],
});
interface LocaleConfig {
label: string;
lang?: string;
dir?: 'ltr' | 'rtl';
}

你可以为每种语言环境设置以下选项:

类型: string

向用户显示的该语言的标签,例如在语言切换器中。通常,你会希望这是该语言的用户期望阅读的名称,例如 "English""العربية""简体中文"

类型: string

该语言的 BCP-47 标签,例如 "en""ar""zh-CN"。如果未设置,则默认使用语言的目录名称。带有区域子标签的语言标签(例如 "pt-BR""en-US")在找不到特定区域的翻译时,将使用其基础语言的内置 UI 翻译。

类型:'ltr' | 'rtl'

该语言的书写方向;"ltr" 表示从左到右(默认值),"rtl" 表示从右到左。

你可以通过设置 root 语言环境来提供没有 /lang/ 目录的默认语言:

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

例如,这允许你将 /getting-started/ 作为英语路由,并使用 /fr/getting-started/ 作为等效的法语页面。

类型: string

设置此站点的默认语言。该值应与 locales 对象的一个键匹配。(如果你的默认语言是你的根语言环境,则可以跳过此项。)

在缺少翻译时,将使用默认语言环境提供回退内容。

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

关于此站点社交媒体帐户的可选详细信息。每个条目将在站点标题中显示为图标链接。

starlight({
social: [
{ icon: 'codeberg', label: 'Codeberg', href: 'https://codeberg.org/knut' },
{ icon: 'discord', label: 'Discord', href: 'https://astro.js.cn/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' },
],
}),

类型:string[]

提供 CSS 文件以自定义 Starlight 网站的外观和感觉。

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

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

类型:{ headingLinks?: boolean }
默认值:{ headingLinks: true }

配置 Starlight 的 Markdown 处理。

类型: boolean
默认值: true

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

starlight({
markdown: {
// Disable Starlight’s clickable heading anchor links.
headingLinks: false,
},
}),

类型: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 特定的属性,以进一步自定义代码块的主题行为:

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

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

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

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

类型: boolean
默认值: true

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

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

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

类型:boolean | PagefindOptions
默认值: true

配置 Starlight 的默认站点搜索提供程序 Pagefind

设置为 false 以禁用使用 Pagefind 索引你的网站。如果正在使用默认搜索 UI,这也将隐藏它。

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

pagefind 设置为一个对象以配置 Pagefind 搜索客户端:

  • 有关使用 pagefind.ranking 选项控制搜索结果排名计算方式的更多详细信息,请参阅 Pagefind 文档中的“自定义 Pagefind 的结果排名”
  • 有关使用 pagefind.mergeIndex 选项控制如何跨多个站点搜索的更多详细信息,请参阅 Pagefind 文档中的“搜索多个站点”
interface PagefindOptions {
ranking?: {
pageLength?: number;
termFrequency?: number;
termSaturation?: number;
termSimilarity?: number;
};
indexWeight?: number;
mergeIndex?: Array<{
bundlePath: string;
indexWeight?: number;
basePath?: string;
baseUrl?: string;
mergeFilter?: Record<string, string | string[]>;
language?: string;
ranking?: {
pageLength?: number;
termFrequency?: number;
termSaturation?: number;
termSimilarity?: number;
};
}>;
}

类型: boolean
默认值: true

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

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

类型:HeadConfig[]

向 Starlight 站点的 <head> 中添加自定义标签。这对于添加分析和其他第三方脚本和资源非常有用。

starlight({
head: [
// Example: add Fathom analytics script tag.
{
tag: 'script',
attrs: {
src: 'https://#/script.js',
'data-site': 'MY-FATHOM-ID',
defer: true,
},
},
],
});

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

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

类型: boolean
默认值: false

控制页脚是否显示页面的最后更新时间。

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

类型: boolean
默认值: true

定义页脚是否应包含上一页和下一页的链接。

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

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

设置网站的默认网站图标路径,该文件应位于 public/ 目录中,并且是有效的图标文件(.ico.gif.jpg.png.svg)。

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

如果你需要设置其他变体或备用网站图标,可以使用 head 选项添加标签:

starlight({
favicon: '/images/favicon.svg',
head: [
// Add ICO favicon fallback for Safari.
{
tag: 'link',
attrs: {
rel: 'icon',
href: '/images/favicon.ico',
sizes: '32x32',
},
},
],
});

类型: string
默认值:'|'

设置页面 <title> 标签中页面标题和网站标题之间的分隔符,该标签显示在浏览器选项卡上。

默认情况下,每个页面的 <title> 都是 页面标题 | 网站标题。例如,此页面的标题为“配置参考”,而此网站的标题为“Starlight”,因此此页面的 <title> 为“配置参考 | Starlight”。

类型: boolean
默认值: false

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

类型:string | string[]

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

有关如何创建路由中间件的详细信息,请参阅路由数据指南

类型:Record<string, string>

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

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

有关可以覆盖的所有组件的详细信息,请参阅覆盖参考

类型:StarlightPlugin[]

使用自定义插件扩展 Starlight。插件会对你的项目应用更改,以修改或增加 Starlight 的功能。

访问插件展示以查看可用插件列表。

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

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

类型: boolean
默认值: false

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

starlight({
credits: true,
});

Starlight 使用 Astro 的内容集合来加载你的内容。Starlight 的内容加载器和模式有助于按需配置集合。

src/content.config.ts
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() }),
// Optional: the i18n collection is used to translate UI in multilingual sites
i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
};

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

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

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

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

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

例如,这对于保留那些会被移除的特殊字符很有用。默认情况下,Example.File.md 会在 /examplefile 路径下提供服务。如果你希望在 /Example.File 路径下提供服务,可以通过定义一个自定义的 generateId() 函数来实现:

docsLoader({
// Remove the `.md` or `.mdx` extension, but otherwise don’t process filenames.
generateId: ({ entry }) => entry.split('.').slice(0, -1).join('.'),
}),

更多详细信息请参阅 generateId() in the Astro docs

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

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

目前没有配置 i18nLoader() 的选项。

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

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

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

类型:Zod 模式或返回 Zod 模式的函数
默认值:z.object({})

使用附加字段扩展 Starlight 的 frontmatter 模式。有关使用 extend 选项的更多详细信息,请参阅“自定义 frontmatter 模式”

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

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

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

使用附加字段扩展 Starlight 的 i18n 模式。有关使用 extend 选项的更多详细信息,请参阅“扩展翻译模式”