配置参考
配置 starlight
集成
Starlight 是在 Astro web 框架之上构建的集成。你可以在 astro.config.mjs
配置文件中配置你的项目:
你可以将以下选项传递给starlight
集成。
title
(必填)
类型: string | Record<string, string>
设置你的网站标题。将用于元数据和浏览器标签标题。
这个值可以是一个字符串,或者对于多语言网站,可以是一个包含每种不同语言值的对象。
当使用对象形式时,键必须是 BCP-47 标签(例如 en
,ar
或 zh-CN
):
description
类型: string
设置你的网站描述。如果页面的 frontmatter 中没有设置 description
,则在 <meta name="description">
标签中与搜索引擎共享元数据。
logo
类型: LogoConfig
在导航栏中设置一个 logo 图片,与网站标题一起显示或替代网站标题。你可以设置单个 src
属性,也可以为 light
和 dark
设置单独的图像源。
LogoConfig
tableOfContents
类型: false | { minHeadingLevel?: number; maxHeadingLevel?: number; }
默认值: { minHeadingLevel: 2; maxHeadingLevel: 3; }
配置每个页面右侧显示的目录。默认情况下,<h2>
和 <h3>
标题将包含在此目录中。
editLink
类型: { baseUrl: string }
通过设置你要使用的 base URL 来启用 “编辑此页” 链接。最终链接将是editLink.baseUrl
+当前页面路径。例如,要启用在 GitHub 上编辑withastro/starlight
仓库中的页面:
使用此配置,/introduction
页面将具有指向 https://github.com/withastro/starlight/edit/main/src/content/docs/introduction.md
的编辑链接。
sidebar
类型: SidebarItem[]
配置你的网站的侧边栏导航项目。
侧边栏是包含链接和链接组的数组。
除了使用 slug
的项目之外,每个项目都必须具有 label
和以下属性之一:
-
link
— 指向特定 URL 的单个链接,例如'/home'
或'https://example.com'
。 -
slug
— 指向一个内部页面的引用, 例如'guides/getting-started'
。 -
items
— 包含更多侧边栏链接和子组的数组。 -
autogenerate
— 指定要从中自动生成一组链接的文档目录的对象。
内部链接也可以被指定为字符串,而不是带有 slug
属性的对象。
排序
自动生成的侧边栏组按文档名字母顺序排序。例如,从 astro.md
生成的页面将显示在 starlight.md
页面上方。
折叠组
默认情况下,链接组是展开的。你可以通过将组的 collapsed
属性设置为 true
来更改此行为。
自动生成的子组默认情况下会遵守其父组的 collapsed
属性。设置 autogenerate.collapsed
属性以覆盖此行为。
翻译标签
如果你的网站是多语言的,每个项目的 label
被认为是默认语言。你可以设置一个 translations
属性来为你支持的其他语言提供标签:
SidebarItem
BadgeConfig
locales
类型: { [dir: string]: LocaleConfig }
为你的网站设置支持的 locales
来配置国际化(i18n)。
每个条目都应该使用该语言文件保存的目录作为 key。
LocaleConfig
你可以为每个语言设置以下选项:
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/
目录的默认语言:
举例,这允许你将 /getting-started/
作为英语路由提供,并将 /fr/getting-started/
作为等效的法语页面。
defaultLocale
类型: string
设置此站点的默认语言。
该值应该与你的 locales
对象的键之一匹配。
(如果你的默认语言是你的root locale,你可以跳过这一步。)
默认语言将用于在缺少翻译时提供回退内容。
social
类型: Partial<Record<'azureDevOps' | 'backstage' | 'bitbucket' | 'blueSky' | 'codeberg' | 'codePen' | 'discord' | 'discourse' | 'email' | 'facebook' | 'farcaster' | 'github' | 'gitlab' | 'gitter' | 'hackerOne' | 'instagram' | 'linkedin' | 'mastodon' | 'matrix' | 'microsoftTeams' | 'nostr' | 'openCollective' | 'patreon' | 'pinterest' | 'reddit' | 'rss' | 'signal' | 'slack' | 'stackOverflow' | 'telegram' | 'threads' | 'tiktok' | 'twitch' | 'twitter' | 'x.com' | 'youtube' | 'zulip', string>>
可选的社交媒体账户详情。添加任何一个都会在网站标题中显示它们作为图标链接。
customCss
类型: string[]
提供 CSS 文件来自定义你的 Starlight 网站的外观和风格。
支持相对于项目根目录的本地 CSS 文件,例如 './src/custom.css'
,以及你安装为 npm 模块的 CSS,例如 '@fontsource/roboto'
。
expressiveCode
类型: StarlightExpressiveCodeOptions | boolean
默认值: true
Starlight 使用 Expressive Code 来渲染代码块,并添加对代码示例的高亮支持,向代码块添加文件名等。 请参阅 “代码块”指南 以了解如何在你的 Markdown 和 MDX 内容中使用 Expressive Code 语法。
你可以通过在 Starlight 的 expressiveCode
选项中设置任何标准的 Expressive Code 配置选项以及一些特定于 Starlight 的属性。比如,设置 Expressive Code 的 styleOverrides
选项来覆盖默认的 CSS。这样就可以自定义代码块,比如给你的代码块添加圆角:
如果你想禁用 Expressive Code,请在 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
默认值: true
定义 Starlight 的默认站点搜索 provider Pagefind 是否启用。
将其设置为 false
以禁用使用 Pagefind 索引你的网站。这也将隐藏默认的搜索 UI。
当 prerender
选项设置为 false
时,无法启用 Pagefind。
prerender
类型: boolean
默认值: true
定义 Starlight 页面是应预渲染为静态 HTML 还是由 SSR 适配器 按需渲染。
默认情况下,Starlight 页面是预渲染的。
如果你正在使用 SSR 适配器并希望按需渲染 Starlight 页面,请设置为 prerender: false
。
head
类型: HeadConfig[]
添加自定义标签到你的 Starlight 网站的 <head>
中。
可以用于添加分析和其他第三方脚本和资源。
在 head
中的条目会直接转换为 HTML 元素,并不会经过 Astro 的 脚本 或 样式 处理。如果你需要导入本地资源,如脚本、样式或图片,请重写 Head 组件。
HeadConfig
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
)图标文件。
如果你需要设置其他变体或回退的 favicon,你可以使用 head
选项添加标签:
titleDelimiter
类型: string
默认值: '|'
设置在页面的 <title>
标签里页面标题和网站标题之间的分隔符,它会显示在浏览器标签上。
默认情况下,每个页面的 <title>
都是 页面标题 | 网站标题
。
举例,本页面的标题是“配置参考”,本站点的标题是“Starlight”,所以本页面的 <title>
是“配置参考 | Starlight”。
disable404Route
类型: boolean
默认值: false
禁用注入 Starlight 的默认 404 页面。要在项目中使用自定义的 src/pages/404.astro
路由,请将此选项设置为 true
。
components
类型: Record<string, string>
提供组件的路径来覆盖 Starlight 的默认实现。
要查阅所有可覆盖的组件,请参阅覆盖参考。
plugins
使用自定义插件扩展 Starlight。 插件将更改应用到你的项目中,以修改或添加 Starlight 的功能。
访问 插件 showcase 查看可用插件列表。
有关创建自己的插件的详细信息,请参阅插件参考。
credits
启用在你的网站页脚显示 “基于 Starlight 构建” 的链接。