跳转到内容

Frontmatter 参考

你可以通过在 Starlight 中为 Markdown 和 MDX 页面设置 frontmatter 的值来对它们进行个性化定制。例如,一个常规页面可能会设置 titledescription 字段:

src/content/docs/example.md
---
title: About this project
description: Learn more about the project I’m working on.
---
Welcome to the about page!

类型: string

你必须为每个页面提供一个标题。它将显示在页面的顶部、浏览器标签页以及页面的元数据中。

类型: string

页面描述用于页面的元数据,搜索引擎和社交媒体预览会使用它。

类型string

覆盖页面的 slug。更多详情请参阅 Astro 文档中的“定义自定义 ID”

类型: string | boolean

覆盖全局的 全局 editLink 配置。设置为 false 可以禁用特定页面的“编辑此页”链接,或者提供一个可编辑此页面内容的备用 URL。

类型: HeadConfig[]

你可以使用 head frontmatter 字段向页面的 <head> 添加额外的标签。这意味着你可以为单个页面添加自定义样式、元数据或其他标签。这与全局的 全局 head 选项类似。

src/content/docs/example.md
---
title: About us
head:
# Use a custom <title> tag
- tag: title
content: Custom about title
---

类型: false | { minHeadingLevel?: number; maxHeadingLevel?: number; }

覆盖全局的 全局 tableOfContents 配置。自定义要包含的标题级别,或将其设置为 false 以在此页面上隐藏目录。

src/content/docs/example.md
---
title: Page with only H2s in the table of contents
tableOfContents:
minHeadingLevel: 2
maxHeadingLevel: 2
---
src/content/docs/example.md
---
title: Page with no table of contents
tableOfContents: false
---

类型: 'doc' | 'splash'
默认值: 'doc'

设置此页面的布局模板。页面默认使用 'doc' 布局。设置为 'splash' 可使用专为落地页设计的更宽的、没有任何侧边栏的布局。

类型: HeroConfig

在此页面顶部添加一个 hero 组件。与 template: splash 配合使用效果很好。

例如,此配置显示了一些常用选项,包括从你的仓库加载图像。

src/content/docs/example.md
---
title: My Home Page
template: splash
hero:
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 图像。

src/content/docs/example.md
---
hero:
image:
alt: A glittering, brightly colored logo
dark: ~/assets/logo-dark.png
light: ~/assets/logo-light.png
---
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>;
}>;
}

类型: { content: string }

在此页面顶部显示一个横幅公告。

content 的值可以包含用于链接或其他内容的 HTML。例如,此页面显示一个包含指向 example.com 的链接的横幅。

src/content/docs/example.md
---
title: Page with a banner
banner:
content: |
We just launched something cool!
<a href="https://example.com">Check it out</a>
---

类型: Date | boolean

覆盖全局的 全局 lastUpdated 选项。如果指定了日期,它必须是有效的 YAML 时间戳,并将覆盖存储在此页面 Git 历史记录中的日期。

src/content/docs/example.md
---
title: Page with a custom last update date
lastUpdated: 2022-08-09
---

类型: boolean | string | { link?: string; label?: string }

覆盖全局的 全局 pagination 选项。如果指定了一个字符串,生成的链接文本将被替换;如果指定了一个对象,链接和文本都将被覆盖。

src/content/docs/example.md
---
# Hide the previous page link
prev: false
---
src/content/docs/example.md
---
# Override the previous page link text
prev: Continue the tutorial
---
src/content/docs/example.md
---
# Override both the previous page link and text
prev:
link: /unrelated-page/
label: Check out this other page
---

类型: boolean | string | { link?: string; label?: string }

prev 相同,但用于下一页的链接。

src/content/docs/example.md
---
# Hide the next page link
next: false
---

类型: boolean
默认值: true

设置此页面是否应包含在 Pagefind 搜索索引中。设置为 false 可将页面从搜索结果中排除。

src/content/docs/example.md
---
# Hide this page from the search index
pagefind: false
---

类型: boolean
默认值: false

设置此页面是否应被视为草稿,并且不包含在生产构建中。设置为 true 将页面标记为草稿,使其仅在开发期间可见。

src/content/docs/example.md
---
# Exclude this page from production builds
draft: true
---

因为草稿页面不包含在构建输出中,所以你不能使用slug将草稿页面直接添加到你的站点侧边栏配置中。用于自动生成侧边栏分组的目录中的草稿页面在生产构建中会自动被排除。

类型: SidebarConfig

在使用自动生成的链接组时,控制此页面在侧边栏中的显示方式。

interface SidebarConfig {
label?: string;
order?: number;
hidden?: boolean;
badge?: string | BadgeConfig;
attrs?: Record<string, string | number | boolean | undefined>;
}

类型: string
默认值: 页面的 title

在自动生成的链接组中显示时,设置此页面在侧边栏中的标签。

src/content/docs/example.md
---
title: About this project
sidebar:
label: About
---

类型: number

在对自动生成的链接组进行排序时,控制此页面的顺序。数字越小,在链接组中显示的位置越高。

src/content/docs/example.md
---
title: Page to display first
sidebar:
order: 1
---

类型: boolean
默认值: false

防止此页面被包含在自动生成的侧边栏组中。

src/content/docs/example.md
---
title: Page to hide from autogenerated sidebar
sidebar:
hidden: true
---

类型: string | BadgeConfig

在自动生成的链接组中显示时,向侧边栏中的页面添加一个徽章。当使用字符串时,徽章将以默认的主题色显示。或者,传递一个包含 textvariantclass 字段的 BadgeConfig 对象来自定义徽章。

src/content/docs/example.md
---
title: Page with a badge
sidebar:
# Uses the default variant matching your site’s accent color
badge: New
---
src/content/docs/example.md
---
title: Page with a badge
sidebar:
badge:
text: Experimental
variant: caution
---

类型: Record<string, string | number | boolean | undefined>

在自动生成的链接组中显示时,添加到侧边栏页面链接的 HTML 属性。如果此页面所属的自动生成组上设置了 autogenerate.attrs,frontmatter 属性将与组属性合并。

src/content/docs/example.md
---
title: Page opening in a new tab
sidebar:
# Opens the page in a new tab
attrs:
target: _blank
---

Starlight 的 docs 内容集合的 frontmatter schema 是在 src/content.config.ts 中使用 docsSchema() 辅助函数配置的。

src/content.config.ts
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() 接受以下选项:

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

通过在 docsSchema() 选项中设置 extend,用额外的字段扩展 Starlight 的 schema。该值应该是一个 Zod schema

在下面的例子中,我们为 description 提供了一个更严格的类型,使其成为必需的,并添加了一个新的可选字段 category

src/content.config.ts
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 扩展的函数。

src/content.config.ts
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(),
});
},
}),
}),
};