mintlify__docs/zh/organize/pages.mdx

---
title: "页面"
description: "使用 MDX 文档顶部的 YAML 前置元数据配置页面元数据、标题、描述、图标和布局模式。"
keywords: ["tags", "tag", "frontmatter", "metadata", "layout"]
---

每个页面对应一个 Markdown 文件。你可以为页面使用 `.mdx` 或 `.md` 任一文件类型。我们推荐使用 MDX，它将 Markdown 与 React 组件结合起来，以创建丰富的交互式文档。纯 Markdown (`.md`) 可以加快从其他平台的迁移，但切换到 MDX 可以启用更多功能。

<div id="page-metadata">
  ## 页面 metadata
</div>

每个页面都以 frontmatter 开始，即文件顶部由 `---` 包裹的 YAML metadata。该 metadata 用于控制页面的呈现与行为。

使用 frontmatter 可以控制：

* 页面标题和说明
* 侧边栏标题、图标和标签
* 页面布局
* SEO (搜索引擎优化) meta 标签
* 自定义 metadata

<ResponseField name="title" type="string">
  显示在导航和浏览器标签页中的页面标题。

  如果省略，Mintlify 会根据路径生成标题。路径的最后一段会作为标题，其中的短横线和下划线会被替换为空格，且首字母会大写。例如，`guides/getting-started.md` 会变为 **入门**。
</ResponseField>

<ResponseField name="description" type="string">
  对本页面内容的简要说明。显示在标题下方，并提升 SEO。
</ResponseField>

<ResponseField name="sidebarTitle" type="string">
  显示在侧边栏导航中的短标题。
</ResponseField>

<ResponseField name="icon" type="string">
  要显示的 icon。

  选项：

  * [Font Awesome icon](https://fontawesome.com/icons) 名称
  * [Lucide icon](https://lucide.dev/icons) 名称
  * [Tabler icon](https://tabler.io/icons) 名称
  * 指向外部托管图标的 URL
  * 项目中图标文件的路径
</ResponseField>

<ResponseField name="iconType" type="string">
  仅适用于 [Font Awesome](https://fontawesome.com/icons) 图标。图标的样式。

  选项：`regular`、`solid`、`light`、`thin`、`sharp-solid`、`duotone`、`brands`。
</ResponseField>

<ResponseField name="tag" type="string">
  显示在侧边栏中页面标题旁的标签。
</ResponseField>

<ResponseField name="hidden" type="boolean">
  设为 `true` 可将页面从侧边栏导航中移除。用户仍可通过其 URL 访问该页面，但搜索引擎不会对其进行索引。要使页面重新可见，请完全移除此字段。**不要**将其设置为 `false`，因为这会导致未定义的行为。详情参见 [Hidden pages](/zh/organize/hidden-pages)。
</ResponseField>

<ResponseField name="noindex" type="boolean">
  设为 `true` 可阻止搜索引擎对该页面进行索引。详情参见 [Disable indexing](/zh/optimize/seo#disable-indexing)。所有在 frontmatter 中包含 `hidden: true` 的页面都会自动获得 `noindex: true`。
</ResponseField>

<ResponseField name="boost" type="number">
  按此倍数放大页面在站内搜索中的排名。使用大于 `1` 的值可优先显示该页面，使用介于 `0` 和 `1` 之间的值可降低其优先级。详情参见 [搜索加权](/zh/optimize/search-boost)。
</ResponseField>

<ResponseField name="deprecated" type="boolean">
  设为 `true` 可在页面标题旁显示"deprecated"标签。可用它标记过时内容或旧版功能，同时保持页面可访问。
</ResponseField>

<ResponseField name="hideFooterPagination" type="boolean">
  设为 `true` 可隐藏页面底部的上一页/下一页导航链接。适用于落地页或参考页等不需要顺序导航的独立页面。
</ResponseField>

<ResponseField name="hideApiMarker" type="boolean">
  设为 `true` 可隐藏侧边栏中页面标题旁的 HTTP 方法标记（如 GET 或 POST）。适用于希望侧边栏外观更简洁的 API 页面。
</ResponseField>

<ResponseField name="groups" type="string[]">
  将页面限制为特定组中的用户。用户必须属于至少一个列出的组才能访问该页面。你必须先配置[身份验证](/zh/deploy/authentication-setup)。详情参见[使用组控制访问](/zh/deploy/authentication-setup#control-access-with-groups)。
</ResponseField>

<ResponseField name="<custom>" type="string">
  任意有效的 YAML frontmatter。例如：`product: "API"` 或 `version: "1.0.0"`。
</ResponseField>

```yaml Example YAML frontmatter wrap
---
title: "关于 frontmatter"
description: "Frontmatter 是控制页面显示和行为的 metadata"
sidebarTitle: "Frontmatter"
icon: "book"
tag: "NEW"
---
```

<div id="page-mode">
  ## 页面模式
</div>

通过 `mode` 设置控制页面的布局。

<div id="default">
  ### 默认
</div>

如果未指定模式，则会使用带有侧边栏导航和目录的标准布局。

```yaml
---
title: "默认页面标题"
---
```

<div id="wide">
  ### 宽屏
</div>

宽屏模式会隐藏目录。对于没有任何标题的页面，或当你希望利用额外的横向空间时，它很实用。所有主题均支持宽屏模式。

```yaml
---
title: "宽页面标题"
mode: "wide"
---
```

<div id="custom">
  ### 自定义
</div>

自定义模式提供极简布局，并移除除顶部导航栏外的所有元素。此模式会隐藏侧边栏、目录和页脚。你可以将自定义模式视为一块空白画布，用于构建落地页或导航元素极少的独特布局。所有主题均支持自定义模式。

```yaml
---
title: "Custom page title"
mode: "custom"
---
```

<Warning>
  `style` 属性可能会在页面加载时导致布局偏移。为避免此问题，建议优先使用 [Tailwind CSS or custom CSS](/zh/customize/custom-scripts)。
</Warning>

<div id="frame">
  ### Frame
</div>

Frame 模式提供与自定义模式类似的布局，但保留侧边栏导航。使用此模式，可以在保持默认导航体验的同时使用自定义 HTML 和组件。Aspen、Almond、Luma 和 Sequoia 主题支持 Frame 模式。

```yaml
---
title: "Frame 页面标题"
mode: "frame"
---
```

<div id="center">
  ### 居中
</div>

居中模式会移除侧边栏和目录，并将内容居中呈现。对于更新日志或其他希望将重点放在内容上的页面，请使用居中模式。Mint、Linden、Willow 和 Maple 主题均支持居中模式。

```yaml
---
title: "居中页面标题"
mode: "center"
---
```

<div id="api-pages">
  ## API 页面
</div>

在你的 frontmatter 中添加 API 规范 (通过设置 `api` 或 `openapi`) ，即可创建交互式 API 操作台。

```yaml
---
openapi: "GET /endpoint"
---
```

进一步了解如何构建 [API 文档](/zh/api-playground/overview)。

<div id="external-links">
  ## 外部链接
</div>

在导航中使用 `url` metadata 直接链接到外部站点。

```yaml
---
title: "npm 包"
url: "https://www.npmjs.com/package/mint"
---
```

<div id="search-engine-optimization">
  ## 搜索引擎优化
</div>

Mintlify 会自动生成大多数 SEO (搜索引擎优化) 元标签。你也可以手动设置 SEO 元标签，以自定义 SEO、社交分享和浏览器兼容性相关的配置。

<Note>
  含有冒号的元标签一定要使用引号括起来。
</Note>

```yaml
---
"twitter:image": "/images/social-preview.jpg"
---
```

有关完整的 SEO (搜索引擎优化) metadata 选项，请参阅 [SEO](/zh/optimize/seo)。

<div id="internal-search-keywords">
  ## 内部搜索关键词
</div>

通过在 metadata 中提供 `keywords`，帮助用户在搜索结果中发现特定页面。这些关键词不会出现在页面内容中。如果用户搜索这些关键词，该页面会出现在搜索结果中。

```yaml
---
keywords: ['配置', '设置', '入门指南']
---
```

<div id="last-modified-timestamp">
  ## 最后修改时间
</div>

在[全局设置](/zh/organize/settings-seo#metadata)中启用 `metadata.timestamp`，即可在所有页面显示“最后修改于 [日期]”时间戳。

```json docs.json
"metadata": {
  "timestamp": true
}
```

你可以在单个页面上使用 frontmatter 中的 `timestamp` 字段来覆盖全局时间戳设置。使用该字段可在特定页面上选择性地显示或隐藏时间戳。

```yaml
---
title: "页面标题"
timestamp: false
---
```

如果将 `timestamp` 设置为 `true`，即使全局设置为 `false`，该页面也始终会显示时间戳。如果将 `timestamp` 设置为 `false`，即使全局设置为 `true`，该页面也会隐藏时间戳。