front-matter

front matter

在项目根目录的 docs 文件夹中创建一个 Markdown 文件，例如 greeting.md 。

text

website
├── docs
│   └── greeting.md
├── src
│   └── pages
├── docusaurus.config.js
└── …

文档可以包含 front matter，在中文语义里是 元数据 / 前置信息 的意思。在文档开头，用 --- 圈起来的区域会被识别为前置信息，可以配置 元数据。

mddocs/my-doc.md

---
tags:
  - Releases
  - docusaurus
---

# 标题

文档内容……

tags

有两种文章归档方式，一种是目录归档（通过 sidebar 控制），一种是标签归档（tags）。

用法：在文档的前置信息中添加 tags 字段，设置文档的标签。

mddocs/my-doc.md

---
tags:
  - Releases
  - docusaurus
---

# 标题

文档内容……

---

通过 docs/tags.yml 可以批量设置标签，允许这几个属性 ：

• label → 标签显示名称
• permalink → 标签页面 URL。该页面列出所有使用该标签的文档（标题、description和链接）。
• description → 标签描述

yamldocs/tags.yml

docusaurus:
  label: '
  
  aurus'
  permalink: '/docusaurus'
  description: 'Docs related to the Docusaurus framework'

在文章中引用：

mddocs/my-doc.md

---
tags:[]
---

# 标题

文档内容……

文档片段

docs/ 中以 _*.md 命令的文档，被视为“文档片段”，默认情况下将被忽略。片段可以被其他文档导入/引用，达到复用的目的。

mdx

import PartialContent from './_partial.mdx';

复用内容示例:

<PartialContent />

<PartialContent /> 导入为文档片段。

---

id

每个文档有唯一的 id 。 默认规则：文档路径（去掉扩展名）就是 ID。

• docs/greeting.md → greeting
• docs/guide/hello.md → guide/hello

可以在前置信息中指定：

mddocs/hello.md

---
id: part1
---

docs/hello.md → docs/part1

slug

默认情况下，文档的 URL 位置派生自文档 ID，而文档 ID 又基于文档的文件路径。

例如 docs/guide/hello.md → 本地 http://localhost:3000/docs/guide/hello → 网站 https://www.example.com/docs/guide/hello 。

---

以下文件名会省略 slug ：

• index
• README
• 与父目录同名的文件（如 docs/Guide/Guide.md ）

docs/guide/index.md →访问 docs/guide

---

自定义 URL：

md

---
  ---

slug 支持：

• 绝对路径： /mySlug 、 /
• 相对路径： mySlug 、 ./../mySlug

---

默认情况下，docs 目录的路由路径为 docs ：

jsdocusaurus.config.js

routeBasePath: "/docs",

slug: /bonjour → /docs/bonjour slug: / → /docs

---

你可以根据偏好，修改 docs 目录的路由路径，例如：

jsdocusaurus.config.js

routeBasePath: "/",

slug: / → / → https://www.example.com

有的人可能会想？把文档设置为主页

sidebar_label

前置信息中使用 sidebar_label 指定在文档侧边栏目录中显示的名称。

md

---
title: Git 基础
sidebar_label: Git 入门
---

它的优先级比 sidebars.js 里（如果有配置）的 label 高。

---

自定义 props

侧边栏自定义 props 是将任意文档元数据传播到客户端的有用方法，因此你可以在使用任何获取文档对象的文档相关钩子时获得其他信息。

您可以使用 sidebar_custom_props 声明文档页面的自定义元数据。需要前端基础+++

displayed_sidebar

当文档同时被多个 sidebar 包含时，明确指定文档使用哪个 sidebar：

jsa.md

---
displayed_sidebar: apiSidebar
---

生成分页

手动设置分页导航：

jswindows.md

---
pagination_next: 上手
---

# Windows 安装

禁用： pagination_next： null

---

元数据汇总表格

（注：部分字段在某些场景下才有效／可选）

字段 (English)	中文名称 / 含义	类型 / 默认值	说明 / 作用
id	文档 ID	string （默认是文件路径，不含扩展名）	文档的唯一标识符，用于内部引用、路由、导航等。若未显式写 id ，Docusaurus 会用路径作为 fallback。 ([docusaurus. io][1])
title	标题	string （默认 fallback 为 id ）	文档的标题。它用于页面 metadata（如 <title> ）、作为侧边栏 / 导航 / 下一页 / 上一页显示的文本。 ([docusaurus. io][1])
pagination_label	分页标签	string （默认取 sidebar_label 或 title ）	用在 “上一篇 / 下一篇” 链接中显示的文本。可以单独设定，覆盖默认逻辑。 ([docusaurus. io][1])
sidebar_label	侧边栏标签	string （默认取 title ）	这个文档在侧边栏中的显示名称。如果想在侧边栏里显示不同于标题的文字，就用这个字段。 ([docusaurus. io][1])
sidebar_position	侧边栏顺序	number	在 “autogenerated”（自动生成）侧边栏中，控制文档在所属类别 / 列表中的排序位置。 ([docusaurus. io][1])
sidebar_class_name	侧边栏 CSS 类名	string	给这个侧边栏项额外添加一个 class 名称，用于定制样式。 ([docusaurus. io][1])
sidebar_custom_props	侧边栏自定义属性	object	给这个侧边栏项存附加数据 (key–value 形式)，可在组件中读取以做扩展用途。 ([docusaurus. io][1])
displayed_sidebar	强制显示某个侧边栏	string	对于一个文档，你可以强制指定使用哪个侧边栏 (尤其当你有多个 sidebar 配置时)。参见 “multiple sidebars” 指南。 ([docusaurus. io][1])
hide_title	隐藏标题	boolean （默认 false ）	如果你在 front matter 中写了 hide_title: true ，那么 render 时会隐藏这个由 front matter 指定的标题（注意：它不会隐藏 Markdown 中用 # 标题 写的那行）。 ([docusaurus. io][1])
hide_table_of_contents	隐藏目录 (TOC)	boolean （默认 false ）	是否在页面中隐藏右侧的自动目录（table of contents）。 ([docusaurus. io][1])
toc_min_heading_level	目录最小 heading 级别	number （默认 2 ）	TOC（目录）中最小 heading 等级（通常是 ## ）要显示。范围 2–6。 ([docusaurus. io][1])
toc_max_heading_level	目录最大 heading 级别	number （默认 3 ）	TOC 中允许显示的最大 heading 级别。范围 2–6。 ([docusaurus. io][1])
pagination_next	下一篇 (分页)	string 或 null	你可以显式指定 “下一篇” 要链接到哪篇文档的 id 。设为 null 表示不显示 “下一篇”。 ([docusaurus. io][1])
pagination_prev	上一篇 (分页)	string 或 null	显式指定 “上一篇” 要链接到哪篇文档的 id 。设为 null 则不显示 “上一篇”。 ([docusaurus. io][1])
parse_number_prefixes	是否解析数字前缀	boolean	用于控制是否对文件名的数字前缀做解析（如 01-Introduction.md 之类）。如果设为 false ，就不会自动处理这一前缀。 ([docusaurus. io][1])
custom_edit_url	自定义编辑链接	string 或 null	可以覆盖插件或配置中给定的 editUrl ，为这个文档单独定义 “Edit this page” 链接。设为 null 表示不显示编辑链接。 ([docusaurus. io][1])
keywords	关键词	string[]	用于 <meta name="keywords" /> ，帮助 SEO 搜索引擎识别页面主题。 ([docusaurus. io][1])
description	描述 (meta 描述)	string （默认是 Markdown 内容的第一行）	页面摘要，用作 <meta name="description" /> 和 Open Graph 的描述，影响 SEO 和社交媒体预览。 ([docusaurus. io][1])
image	封面 / 缩略图	string	用作 Open Graph 的 og:image ，当别人分享此页面时作为预览图。 ([docusaurus. io][1])
slug	自定义路径片段	string	用来指定这个文档 URL 的一部分（即在 /<routeBasePath>/<slug> 的位置）。可以是绝对路径或相对路径。 ([docusaurus. io][1])
tags	标签	Tag[]	给文档打标签。可写成字符串数组（引用 tags.yml 的 key）或写成 { label, permalink } 对象形式。 ([docusaurus. io][1])
draft	草稿文档	boolean （默认 false ）	如果设为 true ，该文档只在开发环境可见，生产构建时不会被包含。 ([docusaurus. io][1])
unlisted	不列出 / 隐藏	boolean （默认 false ）	设为 true 后，文档在生产环境中依然可访问（有链接时），但不会被索引、不会出现在标签页或侧边栏，也不会列入 sitemap。 ([docusaurus. io][1])
last_update	最后更新时间 / 作者	{ date?: string; author?: string }	用于覆盖自动获取的最后更新日期或作者，通常显示在页面底部的 “Last update” 部分。 ([docusaurus. io][1])

---

参考： 📦 plugin-content-docs | Docusaurus