页面 – Mintlify

使用 MDX 文件顶部的 YAML frontmatter 配置页面标题、描述、侧边栏、图标、标签、搜索与 SEO 元数据，并了解页面布局模式、API 页面、外部链接和时间戳设置。本文完整介绍隐藏、索引、可搜索性、搜索加权、相关页面、访问组和上下文菜单等字段，帮助你为文档页面选择合适的布局与行为。

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

页面 metadata

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

所有 frontmatter 字段都是可选的。如果省略 title，Mintlify 会根据文件路径自动生成一个标题。对于不需要自定义 metadata 的页面，你可以完全省略 frontmatter 块。

使用 frontmatter 可以控制：

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

titlestring

显示在导航和浏览器标签页中的页面标题。

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

descriptionstring

对本页面内容的简要说明。显示在标题下方，并提升 SEO。

sidebarTitlestring

显示在侧边栏导航中的短标题。

iconstring

要显示的图标。

选项：

Font Awesome icon 名称
Lucide icon 名称
Tabler icon 名称
单个 emoji（例如 💡 或 🚀）
指向外部托管图标的 URL
项目中图标文件的路径

iconTypestring

仅适用于 Font Awesome 图标，用于指定图标样式。

选项：regular、solid、light、thin、sharp-solid、duotone、brands。

tagstring

显示在侧边栏中页面标题旁的标签。

hiddenboolean

设为 true 可将页面从侧边栏导航中移除。用户仍可通过其 URL 访问该页面，但搜索引擎不会对其进行索引。要使页面重新可见，请完全移除此字段。不要将其设置为 false，因为这会导致未定义的行为。详情参见隐藏页面。

noindexboolean

设为 true 可将该页面从站点搜索、站点地图、搜索引擎索引和 AI 助手 context 中排除。该页面在导航中仍然可见。详情参见停用索引。所有在 frontmatter 中包含 hidden: true 的页面都会自动获得 noindex: true。

searchablebooleandefault: true

默认值为 true。除非显式关闭，否则页面都是可搜索的。设为 false 可将页面从文档站点的搜索结果和 AI 助手 context 中排除，同时保留外部搜索引擎对其的索引，并将其列入站点地图。该页面在导航中仍然可见。详情参见从搜索中排除页面。

boostnumber

按此倍数放大页面在站内搜索中的排名。使用大于 1 的值可优先显示该页面，使用介于 0 和 1 之间的值可降低其优先级。详情参见搜索加权。当 searchable: false 时，boost 无效，因为该页面不会出现在站内搜索结果中。

deprecatedboolean

设为 true 可在页面标题旁显示“deprecated”标签。可用它标记过时内容或旧版功能，同时保持页面可访问。

hideFooterPaginationboolean

设为 true 可隐藏页面底部的上一页/下一页导航链接。适用于落地页或参考页等不需要顺序导航的独立页面。

relatedarray or boolean

要在页面底部 相关主题 部分显示的相关页面列表，或设为 false 以完全隐藏该部分。此字段会覆盖部署的自动推荐。需要启用相关页面 add-on。详情参见相关页面。

hideApiMarkerboolean

设为 true 可隐藏侧边栏中页面标题旁的 HTTP 方法标记（如 GET 或 POST）。适用于希望侧边栏外观更简洁的 API 页面。

contextualobject

为该页面覆盖站点级的上下文菜单。接受与 docs.json 中 contextual 字段相同的 options 数组和 display 值。省略该字段即可继承全局配置，将 options: [] 设为空数组则可在该页面禁用上下文菜单。

groupsstring[]

将页面限制为特定组中的用户。用户必须属于至少一个列出的组才能访问该页面。你必须先配置身份验证。详情参见使用组控制访问。

<custom>string

任意有效的 YAML frontmatter。例如：product: "API" 或 version: "1.0.0"。

Example YAML frontmatter

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

页面模式

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

默认

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

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

宽屏

宽屏模式会隐藏侧边面板，其中包含目录、<Panel> 组件以及 API 请求和响应示例。对于没有任何标题的页面，或当你希望利用额外的横向空间时，它很实用。所有主题均支持宽屏模式。

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

自定义

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

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

style 属性可能会在页面加载时导致布局偏移。为避免此问题，建议优先使用 Tailwind CSS 或自定义 CSS。

Frame

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

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

居中

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

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

助手

助手模式会将页面呈现为全屏助手体验。聊天界面会替换页面的全部内容。使用此模式可以创建供用户与助手互动的专用页面，例如“Ask AI”页面。所有主题均支持助手模式。

要使用助手模式，必须在你的部署中启用助手。如果未启用助手，助手页面模式会显示一个已禁用的搜索字段。

---
title: "询问 AI"
description: "询问如何开始使用产品"
mode: "assistant"
---

API 页面

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

---
openapi: "GET /endpoint"
---

进一步了解如何构建 API 文档。

外部链接

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

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

搜索引擎优化

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

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

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

有关完整的 SEO（搜索引擎优化）metadata 选项，请参阅SEO。

内部搜索关键词

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

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

最后修改时间

在全局设置中启用 metadata.timestamp，即可在所有页面显示“最后修改于 [日期]”时间戳。

docs.json

"metadata": {
  "timestamp": true
}

显示的日期按以下顺序确定：

页面上设置的 frontmatter 字段 lastUpdatedDate（如已设置）。
对于由 GitHub 或 GitLab 支持的部署，最后一次修改页面源文件的 Git 提交日期。
最近一次部署的时间戳。

如需显示特定日期而不是 Git 提交日期，请设置 frontmatter 字段 lastUpdatedDate。当 Git 历史无法反映内容的实际修改时间时（例如从其他系统导入或同步的内容），可使用该字段。

---
title: "页面标题"
lastUpdatedDate: "2026-08-13"
---

若要显式设置显示的日期，请使用 frontmatter 中的 lastUpdatedDate 字段。当 Git 提交历史无法反映内容的真实更新时间时（例如从其他系统同步而来的文档），这一字段非常有用。可使用纯日期值或 ISO 8601 时间戳。

---
title: "页面标题"
lastUpdatedDate: 2026-07-22
---

显示日期的优先级如下：先使用 frontmatter 中的 lastUpdatedDate，其次使用最后一次 Git 提交日期，最后使用最近一次部署的时间戳。当 lastUpdatedDate 的值无效或为空时，会回退为 Git 提交日期。

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

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

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

页面

On this page