Frontmatter 参考
你可以通过在 Starlight 中为 Markdown 和 MDX 页面设置 frontmatter 的值来对它们进行个性化定制。例如,一个常规页面可能会设置 title
和 description
字段:
---title: About this projectdescription: Learn more about the project I’m working on.---
Welcome to the about page!
Frontmatter 字段
标题为“Frontmatter 字段”的部分title
(必填)
标题为“title (必填)”的部分类型: string
你必须为每个页面提供一个标题。它将显示在页面的顶部、浏览器标签页以及页面的元数据中。
description
标题为“description”的部分类型: string
页面描述用于页面的元数据,搜索引擎和社交媒体预览会使用它。
slug
标题为“slug”的部分类型:string
覆盖页面的 slug。更多详情请参阅 Astro 文档中的“定义自定义 ID”。
editUrl
标题为“editUrl”的部分类型: string | boolean
覆盖全局的 全局 editLink
配置。设置为 false
可以禁用特定页面的“编辑此页”链接,或者提供一个可编辑此页面内容的备用 URL。
head
标题为“head”的部分类型: HeadConfig[]
你可以使用 head
frontmatter 字段向页面的 <head>
添加额外的标签。这意味着你可以为单个页面添加自定义样式、元数据或其他标签。这与全局的 全局 head
选项类似。
---title: About ushead: # Use a custom <title> tag - tag: title content: Custom about title---
tableOfContents
标题为“tableOfContents”的部分类型: false | { minHeadingLevel?: number; maxHeadingLevel?: number; }
覆盖全局的 全局 tableOfContents
配置。自定义要包含的标题级别,或将其设置为 false
以在此页面上隐藏目录。
---title: Page with only H2s in the table of contentstableOfContents: minHeadingLevel: 2 maxHeadingLevel: 2---
---title: Page with no table of contentstableOfContents: false---
template
标题为“template”的部分类型: 'doc' | 'splash'
默认值: 'doc'
设置此页面的布局模板。页面默认使用 'doc'
布局。设置为 'splash'
可使用专为落地页设计的更宽的、没有任何侧边栏的布局。
hero
标题为“hero”的部分类型: HeroConfig
在此页面顶部添加一个 hero 组件。与 template: splash
配合使用效果很好。
例如,此配置显示了一些常用选项,包括从你的仓库加载图像。
---title: My Home Pagetemplate: splashhero: title: 'My Project: Stellar Stuff Sooner' tagline: Take your stuff to the moon and back in the blink of an eye. image: alt: A glittering, brightly colored logo file: ~/assets/logo.png actions: - text: Tell me more link: /getting-started/ icon: right-arrow - text: View on GitHub link: https://github.com/astronaut/my-project icon: external variant: minimal attrs: rel: me---
你可以在亮色和暗色模式下显示不同版本的 hero 图像。
---hero: image: alt: A glittering, brightly colored logo dark: ~/assets/logo-dark.png light: ~/assets/logo-light.png---
HeroConfig
标题为“HeroConfig”的部分interface HeroConfig { title?: string; tagline?: string; image?: | { // Relative path to an image in your repository. file: string; // Alt text to make the image accessible to assistive technology alt?: string; } | { // Relative path to an image in your repository to be used for dark mode. dark: string; // Relative path to an image in your repository to be used for light mode. light: string; // Alt text to make the image accessible to assistive technology alt?: string; } | { // Raw HTML to use in the image slot. // Could be a custom `<img>` tag or inline `<svg>`. html: string; }; actions?: Array<{ text: string; link: string; variant?: 'primary' | 'secondary' | 'minimal'; icon?: string; attrs?: Record<string, string | number | boolean>; }>;}
banner
标题为“banner”的部分类型: { content: string }
在此页面顶部显示一个横幅公告。
content
的值可以包含用于链接或其他内容的 HTML。例如,此页面显示一个包含指向 example.com
的链接的横幅。
---title: Page with a bannerbanner: content: | We just launched something cool! <a href="https://example.com">Check it out</a>---
lastUpdated
标题为“lastUpdated”的部分类型: Date | boolean
覆盖全局的 全局 lastUpdated
选项。如果指定了日期,它必须是有效的 YAML 时间戳,并将覆盖存储在此页面 Git 历史记录中的日期。
---title: Page with a custom last update datelastUpdated: 2022-08-09---
prev
标题为“prev”的部分类型: boolean | string | { link?: string; label?: string }
覆盖全局的 全局 pagination
选项。如果指定了一个字符串,生成的链接文本将被替换;如果指定了一个对象,链接和文本都将被覆盖。
---# Hide the previous page linkprev: false---
---# Override the previous page link textprev: Continue the tutorial---
---# Override both the previous page link and textprev: link: /unrelated-page/ label: Check out this other page---
next
标题为“next”的部分类型: boolean | string | { link?: string; label?: string }
与 prev
相同,但用于下一页的链接。
---# Hide the next page linknext: false---
pagefind
标题为“pagefind”的部分类型: boolean
默认值: true
设置此页面是否应包含在 Pagefind 搜索索引中。设置为 false
可将页面从搜索结果中排除。
---# Hide this page from the search indexpagefind: false---
draft
标题为“draft”的部分类型: boolean
默认值: false
设置此页面是否应被视为草稿,并且不包含在生产构建中。设置为 true
将页面标记为草稿,使其仅在开发期间可见。
---# Exclude this page from production buildsdraft: true---
因为草稿页面不包含在构建输出中,所以你不能使用slug将草稿页面直接添加到你的站点侧边栏配置中。用于自动生成侧边栏分组的目录中的草稿页面在生产构建中会自动被排除。
sidebar
标题为“sidebar”的部分类型: SidebarConfig
在使用自动生成的链接组时,控制此页面在侧边栏中的显示方式。
SidebarConfig
标题为“SidebarConfig”的部分interface SidebarConfig { label?: string; order?: number; hidden?: boolean; badge?: string | BadgeConfig; attrs?: Record<string, string | number | boolean | undefined>;}
label
标题为“label”的部分类型: string
默认值: 页面的 title
在自动生成的链接组中显示时,设置此页面在侧边栏中的标签。
---title: About this projectsidebar: label: About---
order
标题为“order”的部分类型: number
在对自动生成的链接组进行排序时,控制此页面的顺序。数字越小,在链接组中显示的位置越高。
---title: Page to display firstsidebar: order: 1---
hidden
标题为“hidden”的部分类型: boolean
默认值: false
防止此页面被包含在自动生成的侧边栏组中。
---title: Page to hide from autogenerated sidebarsidebar: hidden: true---
badge
标题为“badge”的部分类型: string | BadgeConfig
在自动生成的链接组中显示时,向侧边栏中的页面添加一个徽章。当使用字符串时,徽章将以默认的主题色显示。或者,传递一个包含 text
、variant
和 class
字段的 BadgeConfig
对象来自定义徽章。
---title: Page with a badgesidebar: # Uses the default variant matching your site’s accent color badge: New---
---title: Page with a badgesidebar: badge: text: Experimental variant: caution---
attrs
标题为“attrs”的部分类型: Record<string, string | number | boolean | undefined>
在自动生成的链接组中显示时,添加到侧边栏页面链接的 HTML 属性。如果此页面所属的自动生成组上设置了 autogenerate.attrs
,frontmatter 属性将与组属性合并。
---title: Page opening in a new tabsidebar: # Opens the page in a new tab attrs: target: _blank---
自定义 frontmatter schema
标题为“自定义 frontmatter schema”的部分Starlight 的 docs
内容集合的 frontmatter schema 是在 src/content.config.ts
中使用 docsSchema()
辅助函数配置的。
import { defineCollection } from 'astro:content';import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';import { docsSchema } from '@astrojs/starlight/schema';
export const collections = { docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),};
在 Astro 文档的“定义集合 schema”中了解更多关于内容集合 schema 的信息。
docsSchema()
接受以下选项:
extend
标题为“extend”的部分类型: Zod schema 或返回 Zod schema 的函数
默认值: z.object({})
通过在 docsSchema()
选项中设置 extend
,用额外的字段扩展 Starlight 的 schema。该值应该是一个 Zod schema。
在下面的例子中,我们为 description
提供了一个更严格的类型,使其成为必需的,并添加了一个新的可选字段 category
:
import { defineCollection, z } from 'astro:content';import { docsLoader } from '@astrojs/starlight/loaders';import { docsSchema } from '@astrojs/starlight/schema';
export const collections = { docs: defineCollection({ loader: docsLoader(), schema: docsSchema({ extend: z.object({ // Make a built-in field required instead of optional. description: z.string(), // Add a new field to the schema. category: z.enum(['tutorial', 'guide', 'reference']).optional(), }), }), }),};
要利用 Astro 的 image()
辅助函数,请使用一个返回你的 schema 扩展的函数。
import { defineCollection, z } from 'astro:content';import { docsLoader } from '@astrojs/starlight/loaders';import { docsSchema } from '@astrojs/starlight/schema';
export const collections = { docs: defineCollection({ loader: docsLoader(), schema: docsSchema({ extend: ({ image }) => { return z.object({ // Add a field that must resolve to a local image. cover: image(), }); }, }), }),};