跳到主要内容
预计阅读时间：13 分钟

Front Matter的使用方法

1 什么是 Front Matter？​

Front Matter 是写在 Markdown 文件最顶部的一段 YAML 格式的元数据块，用三条短横线 --- 包裹：

---
title: 页面标题
description: 页面描述
---

正文内容从这里开始...

Docusaurus 会解析这些字段来控制页面的标题、URL、侧边栏位置、SEO 信息等行为。

2 常见使用场景​

场景说明
控制侧边栏排序通过 sidebar_position 指定文档在侧边栏中的顺序
自定义页面 URL通过 slug 自定义页面路径，不受文件名限制
SEO 优化通过 description、keywords、image 提升搜索引擎可见性
草稿管理通过 draft 标记未完成的文档，生产构建时自动排除
博客作者与标签通过 authors、tags 管理博客文章的归属和分类
隐藏页面元素通过 hide_title、hide_table_of_contents 隐藏标题或目录

3 Docs（文档）Front Matter 字段​

以下字段适用于 /docs 目录下的 .md / .mdx 文件。

3.1 id​

  • 类型：string
  • 默认值：不含扩展名的文件路径（相对于 docs 根目录）
  • 作用：文档的唯一标识符，用于侧边栏配置和文档间引用。
---
id: my-doc-id
---
注意

通常不需要手动设置，Docusaurus 会自动根据文件路径生成。仅在需要覆盖默认 ID 时使用。

3.2 title​

  • 类型：string
  • 默认值：文档中的第一个 # 标题，若无则使用 id
  • 作用：页面标题，同时用于浏览器标签页标题、侧边栏显示（如未设置 sidebar_label）和 SEO。
---
title: 快速入门指南
---

3.3 hide_title​

  • 类型：boolean
  • 默认值：false
  • 作用：隐藏页面顶部自动渲染的标题（<h1>）。适用于标题已经包含在正文内容中、或使用自定义头部组件的场景。
---
title: 我的页面
hide_title: true
---

3.4 description​

  • 类型：string
  • 默认值：正文的第一段文字
  • 作用：页面的 <meta name="description"> 内容，影响搜索引擎摘要和社交媒体分享预览。
---
description: 本文介绍如何在 5 分钟内完成 Docusaurus 项目的初始化。
---

3.5 sidebar_label​

  • 类型：string
  • 默认值：title 的值
  • 作用：覆盖侧边栏中显示的文本。当 title 过长时，可以设置一个更短的侧边栏标签。
---
title: 完整的 Docusaurus 配置参考手册
sidebar_label: 配置参考
---

3.6 sidebar_position​

  • 类型：number
  • 默认值：按字母顺序排列
  • 作用：控制文档在侧边栏中的排列顺序，数字越小越靠前。
---
sidebar_position: 1
---
注意

同一目录下的多个文档应避免使用相同的 sidebar_position 值，否则排序结果不确定。

3.7 sidebar_class_name​

  • 类型：string
  • 作用：为该文档在侧边栏中的条目添加自定义 CSS 类名，可用于特殊样式（如标红、加粗等）。
---
sidebar_class_name: sidebar-highlight
---

3.8 sidebar_custom_props​

  • 类型：object
  • 作用：为侧边栏条目附加自定义属性，可在自定义侧边栏组件中读取使用。
---
sidebar_custom_props:
  icon: "🔥"
  badge: "NEW"
---

3.9 pagination_label​

  • 类型：string
  • 默认值：sidebar_label 或 title
  • 作用：自定义页面底部"上一篇 / 下一篇"导航中显示的文本。
---
pagination_label: 下一步：安装依赖
---

3.10 pagination_next​

  • 类型：string | null
  • 默认值：侧边栏中的下一篇文档
  • 作用：指定页面底部"下一篇"的链接目标。设为 null 可隐藏"下一篇"按钮。
---
pagination_next: getting-started/installation
---

3.11 pagination_prev​

  • 类型：string | null
  • 默认值：侧边栏中的上一篇文档
  • 作用：指定页面底部"上一篇"的链接目标。设为 null 可隐藏"上一篇"按钮。
---
pagination_prev: null
---

3.12 slug​

  • 类型：string
  • 默认值：文件路径
  • 作用：自定义文档的 URL 路径。
---
slug: /my-custom-url
---
注意
  • 以 / 开头表示绝对路径（相对于 docs 根目录）
  • 不以 / 开头表示相对路径
  • 避免不同文档设置了相同的 slug，会导致路由冲突

3.13 tags​

  • 类型：string[] 或 object[]
  • 作用：为文档添加标签，方便分类检索。
# 简写形式
---
tags: [docusaurus, 入门, 配置]
---

# 完整形式（可自定义 permalink）
---
tags:
  - label: Docusaurus
    permalink: docusaurus
  - label: 入门
    permalink: getting-started
---

3.14 keywords​

  • 类型：string[]
  • 作用：设置页面的 <meta name="keywords"> 标签，用于 SEO。
---
keywords: [docusaurus, 静态站点, markdown]
---

3.15 image​

  • 类型：string
  • 作用：社交媒体分享时的封面图（Open Graph / Twitter Card），也用于 <meta property="og:image">。
---
image: /img/docusaurus-social-card.jpg
---

3.16 custom_edit_url​

  • 类型：string | null
  • 默认值：根据 docusaurus.config.ts 中的 editUrl 自动生成
  • 作用：覆盖页面底部"编辑此页"按钮的链接地址。设为 null 可隐藏编辑按钮。
---
custom_edit_url: https://github.com/my-repo/edit/main/docs/my-doc.md
---

3.17 draft​

  • 类型：boolean
  • 默认值：false
  • 作用：标记为草稿。草稿文档仅在开发模式（npm start）下可见，生产构建时会被排除。
---
draft: true
---

3.18 unlisted​

  • 类型：boolean
  • 默认值：false
  • 作用：将页面设为"未列出"状态。页面仍可通过直接 URL 访问，但不会出现在侧边栏、搜索结果和导航中。构建时会添加 <meta name="robots" content="noindex">。
---
unlisted: true
---
draft 与 unlisted 的区别
  • draft: true —— 生产环境完全不可访问
  • unlisted: true —— 生产环境可通过 URL 访问，但不在导航和搜索中出现

3.19 last_update​

  • 类型：object（含 date 和 author 字段）
  • 默认值：由 Git 提交记录自动生成（需在 docusaurus.config.ts 中启用）
  • 作用：手动指定文档的最后更新时间和作者信息，优先级高于 Git 自动检测。
---
last_update:
  date: 2026-02-24
  author: 张三
---
注意

项目已在 docusaurus.config.ts 中启用了 showLastUpdateTime 和 showLastUpdateAuthor，所以通常无需手动设置此字段，Git 会自动提供。仅在需要覆盖 Git 记录时使用。

3.20 hide_table_of_contents​

  • 类型：boolean
  • 默认值：false
  • 作用：隐藏页面右侧的目录导航（Table of Contents）。
---
hide_table_of_contents: true
---

3.21 toc_min_heading_level​

  • 类型：number（2-6）
  • 默认值：2
  • 作用：目录中显示的最小标题级别。
---
toc_min_heading_level: 2
---

3.22 toc_max_heading_level​

  • 类型：number（2-6）
  • 默认值：3
  • 作用：目录中显示的最大标题级别。
---
toc_min_heading_level: 2
toc_max_heading_level: 4
---

上面的配置表示目录会显示 ##、###、#### 三个级别的标题。

3.23 parse_number_prefixes​

  • 类型：boolean
  • 默认值：取决于全局配置 docs.numberPrefixParsing
  • 作用：控制是否解析文件名中的数字前缀（如 01-intro.md 中的 01）来设置 sidebar_position。
---
parse_number_prefixes: false
---

4 Blog（博客）Front Matter 字段​

以下字段适用于 /blog 目录下的 .md / .mdx 文件。

4.1 title​

  • 类型：string
  • 默认值：文档中的第一个 # 标题
  • 作用：博客文章标题。
---
title: 我的第一篇博客
---

4.2 date​

  • 类型：string（日期格式）
  • 默认值：从文件名或文件夹名中提取（如 2026-02-24-my-post.md）
  • 作用：文章的发布日期，影响排序和显示。
---
date: 2026-02-24
---

# 也支持完整的日期时间格式
---
date: 2026-02-24T10:00
---
注意

如果文件名已包含日期（如 2026-02-24-hello.md），则不需要在 front matter 中重复设置。

4.3 authors​

  • 类型：string | string[] | object | object[]
  • 作用：指定文章作者。可以内联定义，也可以引用 blog/authors.yml 中预定义的作者。
# 引用 authors.yml 中的作者
---
authors: yangshun
---

# 引用多个作者
---
authors: [yangshun, slorber]
---

# 内联定义作者
---
authors:
  - name: 张三
    title: 前端工程师
    url: https://github.com/zhangsan
    image_url: https://github.com/zhangsan.png
    email: zhangsan@example.com
---

blog/authors.yml 中的预定义格式：

zhangsan:
  name: 张三
  title: 前端工程师
  url: https://github.com/zhangsan
  image_url: https://github.com/zhangsan.png

4.4 tags​

  • 类型：string[] 或 object[]
  • 作用：为博客文章添加标签，会自动生成标签聚合页。
---
tags: [docusaurus, 前端, 教程]
---

# 完整形式
---
tags:
  - label: Docusaurus
    permalink: docusaurus
---

4.5 slug​

  • 类型：string
  • 默认值：根据文件路径和日期自动生成
  • 作用：自定义博客文章的 URL 路径。
---
slug: welcome
---

最终 URL 为 /blog/welcome

4.6 description​

  • 类型：string
  • 默认值：正文第一段
  • 作用：文章描述，用于 SEO 和博客列表页的摘要。
---
description: 这篇文章介绍了如何使用 Docusaurus 搭建个人博客。
---

4.7 image​

  • 类型：string
  • 作用：文章封面图，用于社交媒体分享和博客列表展示。
---
image: /img/blog/my-post-cover.png
---

4.8 keywords​

  • 类型：string[]
  • 作用：SEO 关键词，同 Docs 的 keywords。
---
keywords: [博客, docusaurus, 教程]
---

4.9 hide_table_of_contents​

  • 类型：boolean
  • 默认值：false
  • 作用：隐藏目录导航。
---
hide_table_of_contents: true
---

4.10 toc_min_heading_level / toc_max_heading_level​

用法与 Docs 中相同，控制目录显示的标题层级范围。

4.11 draft​

  • 类型：boolean
  • 默认值：false
  • 作用：标记为草稿，仅开发模式可见。
---
draft: true
---

4.12 unlisted​

  • 类型：boolean
  • 默认值：false
  • 作用：不在博客列表和 RSS 中显示，但可通过 URL 直接访问。
---
unlisted: true
---

4.13 reading_time​

  • 类型：number
  • 默认值：根据文章字数自动计算
  • 作用：手动覆盖预估阅读时间（单位：分钟）。
---
reading_time: 5
---

5 Pages（独立页面）Front Matter 字段​

以下字段适用于 /src/pages 目录下的 .md / .mdx 文件。

5.1 title​

---
title: 关于我们
---

5.2 description​

---
description: 了解我们的团队和愿景。
---

5.3 keywords​

---
keywords: [关于, 团队]
---

5.4 image​

---
image: /img/about-og.png
---

5.5 wrapperClassName​

  • 类型：string
  • 作用：为页面的外层容器添加自定义 CSS 类名，可用于自定义页面布局。
---
wrapperClassName: my-custom-page
---

5.6 hide_table_of_contents​

---
hide_table_of_contents: true
---

5.7 draft / unlisted​

用法与 Docs、Blog 中相同。

6 完整示例​

6.1 Docs 文档示例​

---
title: 快速入门
sidebar_label: 快速入门
sidebar_position: 1
description: 5 分钟内完成 Docusaurus 项目搭建。
keywords: [docusaurus, 快速入门, 安装]
tags: [入门, 教程]
image: /img/getting-started.png
slug: /quick-start
last_update:
  date: 2026-02-24
  author: 站点维护者
---

6.2 Blog 博客示例​

---
title: Docusaurus 3.0 正式发布
slug: docusaurus-3-release
date: 2026-02-24
authors:
  - name: 张三
    title: 前端工程师
    image_url: https://github.com/zhangsan.png
tags: [发布, docusaurus]
description: Docusaurus 3.0 带来了全新的功能和改进。
image: /img/blog/v3-release.png
reading_time: 8
---

6.3 Pages 页面示例​

---
title: 关于
description: 关于本站的介绍。
wrapperClassName: about-page
---

7 注意事项​

  1. Front Matter 必须位于文件最顶部，前面不能有空行或其他内容，否则不会被解析。
  2. YAML 语法要求严格：冒号后必须有空格，缩进使用空格而非 Tab。
  3. 字符串值包含特殊字符时需用引号包裹，例如含有 : 的字符串： 
    title: "FAQ: 常见问题"
  4. draft: true 的文档不会出现在生产构建中，适合用于未完成的内容。
  5. slug 冲突会导致构建失败，确保每个文档的 slug 唯一。
  6. 同目录下的文档建议统一使用 sidebar_position，避免部分使用部分不使用导致排序混乱。