Frontmatter介绍
📘 Markdown 文件中的 Frontmatter 介绍
Docusaurus 是一个基于 React 的静态网站生成器，专为文档网站设计。它使用 YAML 格式的 Frontmatter 来配置和控制 Markdown 文件（无论是文档、博客文章还是常规页面）的显示和行为。
Docusaurus 的 Frontmatter 字段根据文件类型（文档、博客或常规页面）有所不同。以下是针对这三种主要文件类型的详细介绍。
1. 📚 文档 (Docs) Frontmatter
文档 Frontmatter 是 Docusaurus 中使用最广泛的，用于配置左侧导航栏、版本控制和页面元数据。
| 字段名 (Key) | 格式/类型 | 描述 | 示例值 |
|---|---|---|---|
id | 字符串 | 必填。用于唯一标识文档，并且在 URL 和侧边栏中引用。通常是文件名（不含扩展名）。 | introduction |
title | 字符串 | 文档在侧边栏和浏览器标题栏中显示的标题。如果没有设置，则使用 Markdown 文件的第一个 H1 标题。 | "Docusaurus 简介" |
sidebar_label | 字符串 | 文档在左侧侧边栏中显示的名称。如果没有设置，则使用 title。 | "入门指南" |
slug | 字符串 | 可选。自定义此文档的 URL 路径片段。 | /intro |
hide_title | 布尔值 | 如果为 true，则不在页面主体中显示文档标题。 | true |
hide_table_of_contents | 布尔值 | 如果为 true，则隐藏右侧的目录 (TOC)。 | true |
sidebar_position | 数字 | 控制文档在侧边栏中的排序位置（升序）。 | 1 或 10 |
description | 字符串 | 页面 <meta name="description"> 标签的内容，对 SEO 很重要。 | "关于 Docusaurus 的基础介绍。" |
keywords | 字符串数组 | 页面 <meta name="keywords"> 标签的内容。 | ['react', 'docusaurus'] |
文档示例
---
id: getting-started
title: 开始使用 Docusaurus
sidebar_label: 🚀 快速入门
description: 这是关于如何开始使用 Docusaurus 的官方指南。
sidebar_position: 1
slug: /start
---
# 欢迎使用
这是文档的正文内容...
2. 📝 博客 (Blog) Frontmatter
博客 Frontmatter 主要用于管理发布日期、作者、分类和标签等信息。
| 字段名 (Key) | 格式/类型 | 描述 | 示例值 |
|---|---|---|---|
title | 字符串 | 必填。博客文章的标题。 | "Docusaurus 2.0 正式发布" |
authors | 字符串数组/对象数组 | 可选。指定文章作者。通常用于引用 docusaurus.config.js 中配置的作者 ID。 | ['lucas', 'sarah'] |
date | 日期/字符串 | 必填。文章的发布日期。影响博客列表中的排序和显示。 | 2025-11-26 |
tags | 字符串数组 | 文章的标签。用于生成标签页面。 | ['release', 'update', 'react'] |
slug | 字符串 | 可选。自定义博客文章的 URL 路径。 | /docusaurus-release-2-0 |
description | 字符串 | 页面 <meta name="description">。如果未提供，将使用文章的摘要 (excerpt)。 | "Docusaurus 2.0 的新特性介绍。" |
keywords | 字符串数组 | 页面 <meta name="keywords">。 | ['blog', 'docusaurus', 'v2'] |
hide_table_of_contents | 布尔值 | 如果为 true，则隐藏右侧的目录 (TOC)。 | true |
博客示例
---
title: Docusaurus 最佳实践
description: 一些可以提升您的 Docusaurus 网站性能和可维护性的技巧。
slug: best-practices
authors: [chris, admin]
tags: ['tip', 'guide', 'best-practice']
date: 2025-11-26
---
这是一篇关于 Docusaurus 最佳实践的博客文章...
3. 📄 页面 (Pages) Frontmatter
对于放在 /src/pages 目录下的常规 Markdown 页面，Frontmatter 相对简单，主要控制 SEO 和布局。
| 字段名 (Key) | 格式/类型 | 描述 | 示例值 |
|---|---|---|---|
title | 字符串 | 页面标题，用于浏览器标题栏。 | "关于我们" |
description | 字符串 | 页面 <meta name="description"> 标签的内容，对 SEO 很重要。 | "这是我们团队的官方介绍页面。" |
keywords | 字符串数组 | 页面 <meta name="keywords"> 标签的内容。 | ['team', 'docusaurus', 'company'] |
custom_edit_url | 字符串 | 可选。覆盖默认的“编辑此页”链接。 | https://github.com/.../about.md |
页面示例
---
title: 贡献指南
description: 了解如何为我们的文档和代码库做出贡献。
keywords: ['contribute', 'guidelines', 'help']
---