版本：Canary 🚧

创建文档

创建名为 greeting.md 的 Markdown 文件，把它放在 docs 目录下。

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

----
description: 创建一个内容丰富的文档页面。
---

## 来自 Docusaurus 的问候

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

## 标题

会显示在右上方的目录

这样，你的用户不用通读全文就可以知晓这篇文章的主要内容。

## 目录默认只包括 h2 和 h3 标题。

你可以在每个文档或主题配置中设置目录包含的标题层级。

标题会保持恰当的间距，让文章看起来层级清晰。

- 列表可以帮助您
- 阐述关键点
- 使读者记忆深刻
  - 并且您可以将它们
    - 嵌套多次

备注

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

你可以阅读更多关于导入页面片段的内容。

文档前言

前言是用来为你的文档页面提供额外的元数据的。前言是可选的——Docusaurus 能够自行推断所有必要的元数据，无需前言。例如，下面引入的 doc tags 功能需要使用前言。关于所有可能的字段，请参阅 API文档。

文档标签

Tags 已经在前言中被声明，并且在文档侧边栏之外，引入了另一个分类层面。

可以定义内联标签，也可以引用 tags file 里的预定义标签（通常使用 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: [演示, 开始上手] 的语法定义。

你也可以阅读更多关于所有的 Yaml 数组声明语法的内容。

组织文件夹结构

docs 文件夹下 Markdown 文件的排列可能对 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 位置是相对于 docs 文件夹的文件路径，但有一些例外。也就是说，如果一个文件被命名为以下任意一个，文件名将不会被包含在 URL中：

名为 index（大小写不敏感）：docs/Guides/index.md
名为 README（大小写不敏感）：docs/Guides/README.mdx
和上一级目录的名字一致：docs/Guides/Guides.md

在上述情况下，默认 slug 将只是 /Guides , 而不是 /index 、/README ，或 /Guides/Guides 的样子。

备注

此约定与目录索引约定完全一致。但是，isCategoryIndex 配置_不会_作用于文档的 URL 。

你可以用 slug 前言来更改文档的 URL。

比如，假设你的网站结构长得像这样：

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

默认情况下，hello.md 可以在 /docs/guide/hello 处访问。你也可以把它的 URL 位置修改为 /docs/bonjour：

---
slug: /bonjour
---

Lorem ipsum

slug 会被添加到文档插件的 routeBasePath 后面。routeBasePath 默认是 /docs。请参考仅文档模式，了解怎么从 URL 中去掉 /docs 部分。

备注

你可以使用：

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

如果你想要让一篇文档位于网站根部下，有形如 https://docusaurus.io/docs/ 的路径，那么你可以这么填写前言中的 slug：

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

Lorem ipsum

侧边栏

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

我们关于文件系统组织的建议是：让你的文件系统和侧边栏结构保持一致（这样你就不需要手写你的 sidebars.js 文件），并使用 slug 前言来自定义每个文档的 URL。

文档前言​

文档标签​

组织文件夹结构​

文档 ID​

文档 URL​

侧边栏​

文档前言

文档标签

组织文件夹结构

文档 ID

文档 URL

侧边栏