版本：3.9.2

创建文档

创建一个叫做 greeting.md 的 markdown 文件，并且把它放到 docs 目录下。

website # 你的网站的根目录
├── docs
│   └── greeting.md
├── src
│   └── pages
├── docusaurus.config.js
├── ...

---
description: 创建包含丰富内容的文档页面。
---

# 你好，来自 Docusaurus

你准备好为你的开源项目创建文档站点了么？

## 标题

会显示在页面右上方的目录中

这样你的用户无需向下滚动或阅读太多内容，就能了解本页的主题。

## 默认情况下，只有 h2 和 h3 级别的标题会出现在目录中。

你可以按文档或在主题配置中设置目录的标题级别。

标题间距合适，层次结构清晰。

- 列表将帮助你
- 列出关键点
- 你希望用户记住的内容
  - 你还可以嵌套它们
    - 多次嵌套

备注

在 docs 目录下所有带有下划线（_）前缀的文件都会被当作页面“片段”，并被默认忽略。

了解有关导入部分页面的更多信息。

文档前言

前言用于为您的文档页面提供额外的元数据。前言是可选的——Docusaurus 能够自行推断所有必要的元数据，无需前言。例如，下面介绍的文档标签功能就需要使用前置元数据。有关所有可用字段，请参阅API 文档。

文档标签

标签在 front matter 中声明，并在 docs 侧边栏之外引入了另一个分类维度。

可以内联定义标签，也可以引用在标签文件（可选，通常为 docs/tags.yml）中声明的预定义标签。

下面的示例：

docusaurus 引用了在 docs/tags.yml 中声明的预定义标签键
Releases 是一个内联标签，因为它不存在于 docs/tags.yml 中

docs/my-doc.md
---
tags:
  - Releases
  - docusaurus
---

# Title

Content

docs/tags.yml
docusaurus:
  label: 'Docusaurus'
  permalink: '/docusaurus'
  description: '与 Docusaurus 框架相关的文档'

提示

标签也可以用 tags: [Demo, 入门] 来声明。

进一步了解所有可能的 Yaml 数组语法。

组织文件夹结构

Markdown文件在docs文件夹下的排列方式会对Docusaurus内容生成产生多方面的影响。然而，其中绝大多数可以与文件结构脱钩。

文档 ID

每个文档都有一个唯一的 id。默认情况下，文档的 id 是文档相对于根文档目录的名称（不包含扩展名）。

例如，greeting.md 的 ID 是 greeting，而 guide/hello.md 的 ID 是 guide/hello。

website # 你的网站的根目录
└── docs
   ├── greeting.md
   └── guide
      └── hello.md

然而，id 的最后部分可由用户在前置信息中定义。例如，如果 guide/hello.md 的内容定义如下，其最终的 id 为 guide/part1。

---
id: part1
---

Lorem ipsum

当手写侧边栏，或这使用与文档相关的布局或钩子时，ID 会被用来指代某篇文档。

文档 URL

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

如果文件命名为以下之一，那么该文件名将不会包含在 URL 中：

Named as index (case-insensitive): docs/Guides/index.md
Named as README (case-insensitive): docs/Guides/README.mdx
Same name as parent folder: docs/Guides/Guides.md

在所有情况下，默认的 slug 都只会是 /Guides，不包含 /index、/README 或重复的 /Guides 段。

备注

该约定与类别索引约定完全相同。然而，isCategoryIndex 配置并不影响文档的 URL。

使用 slug 前置元数据来提供显式的文档 URL 并覆盖默认的 URL。

例如，假设你的站点结构如下所示：

website # 你的网站的根目录
└── docs
    └── guide
        └── hello.md

默认情况下，hello.md 将可在 /docs/guide/hello 路径访问。你可以将其 URL 位置更改为 /docs/bonjour：

---
slug: /bonjour
---

Lorem ipsum

slug 将被附加到文档插件的 routeBasePath 后面，该路径默认为 /docs。有关如何从 URL 中移除 /docs 部分，请参阅仅文档模式。

备注

可以使用：

绝对路径标识：slug: /mySlug、slug: /……
相对路径标识：slug: mySlug、slug: ./../mySlug……

提示

更改文档的文件名或 id 将改变其默认 URL。为防止重命名文件时固定链接失效，建议设置明确的 slug 以保持网址稳定。

在根目录下提供文档

如果您希望文档在根路径下可用，并具有类似 https://docusaurus.io/docs/ 的路径，您可以使用 slug 前置元数据：

---
id: my-home-doc
slug: /
---

Lorem ipsum

侧边栏

使用自动生成侧边栏时，文件夹的结构将决定侧边栏结构。

我们推荐的文件系统组织方式是：让你的文件系统与侧边栏结构保持一致（这样你就不需要手动编写 sidebars.js 文件），并使用 slug 前置元数据来自定义每个文档的 URL。

文档前言​

文档标签​

组织文件夹结构​

文档 ID​

文档 URL​

在根目录下提供文档​

侧边栏​