---
title: "Frontmatter"
description: "文档 schema 支持的所有 frontmatter 字段，包含类型和默认值。"
---
> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# Frontmatter
Frontmatter 在构建时通过 Zod schema 进行校验，错误信息面向内容作者——缺失字段会被指出，非法值会被回显。只有 `title` 是必填项。
字段
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `title` | string | — | **必填。** 页面标题和默认侧边栏标签。 |
| `description` | string | — | Meta 描述和搜索摘要。 |
| `mode` | `"doc"` \| `"custom"` | `"doc"` | `custom` 会移除所有文档装饰。 |
| `sidebar` | `false` \| object | — | `false` 移除此页面的侧边栏列；使用 `sidebar.hidden` 在导航栏中隐藏页面。见下文。 |
| `hideChildren` | boolean | — | `sidebar.hideChildren` 的顶层别名——将一个章节折叠为单个链接。 |
| `head` | array | `[]` | 额外的 `` 元素；与 `config.head` 合并。 |
| `banner` | object | — | 页面级公告，显示在页面头部上方。见下文。 |
| `draft` | boolean | `false` | 从生产构建和 `llms.txt` 索引中排除。 |
| `noindex` | boolean | `false` | 输出 ``。 |
| `searchable` | boolean | 派生自 `noindex` | 是否纳入站点搜索索引。 |
| `tableOfContents` | `false` \| object | — | `{ minHeadingLevel, maxHeadingLevel }`（默认 2–3）。 |
| `lastUpdated` | date | — | 覆盖从 git 推导的日期。 |
| `socialImage` | string | — | 页面级 OG 图片，绝对 URL 或不含基础路径的逻辑路径。 |
| `prev` / `next` | string \| object \| `false` | — | 覆盖或禁用分页链接。 |
| `previousSlug` | string \| string[] | — | 版本重命名入口——参见[重定向](/navigation/redirects)。 |
| `external_link` | URL \| `/path` | — | 重写侧边栏链接目标。 |
```yaml
sidebar:
order: 2
label: Quickstart # 覆盖导航栏中的标题
badge:
text: New
variant: tip # default | info | note | success | tip | warning | caution | danger
hidden: false # 保留页面但从导航栏中隐藏
hideChildren: false # 将一个章节折叠为单个链接
group: # 当此页面是目录的 index.mdx 时
label: Getting started
badge: Beta
```
Banner
使用 `banner` 为页面添加特定公告，如发布通知、迁移提醒或弃用警告：
```yaml
---
title: Workers
banner:
content: This API is in beta and may change.
type: caution
---
```
`content` 为纯文本。`type` 接受 `note`、`tip`、`caution` 或 `danger`。
添加 `dismissible` 可让读者关闭公告：
```yaml
banner:
content: v2 is out — see the migration guide.
type: tip
dismissible:
id: v2-release
days: 7
```
`id` 标识关闭记录。当消息内容变更时更改 `id`，公告会重新显示。`days` 控制关闭记录的持续时长；省略则永久记住关闭状态。
如需全站公告，请在 `BaseLayout` 中渲染 `Banner` 组件。参见[布局](/styling/layouts)。
示例
```yaml
---
title: Configuration
description: Every option defineConfig accepts.
sidebar:
order: 9
badge:
text: Reference
variant: info
tableOfContents:
maxHeadingLevel: 2
---
```
已移除的字段
一些旧字段现在会抛出引导式迁移错误，而不是静默失败：
- `template` → `mode`（`splash` → `custom`）
- `pagefind` → `searchable`
- `llms`、`aiDeprioritize`、`hero` — 已移除；使用 `noindex` 或在正文中组合实现。
Source: https://nimbus-docs.cn/writing/frontmatter/index.mdx