版本：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

By default, the document's URL location is derived from the document id, which in turn is based on the document's file path.

If a file is named one of the following, the file name won't be included in the URL:

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

In all cases, the default slug would only be /Guides, without the /index, /README, or duplicate /Guides segment.

备注

This convention is exactly the same as the category index convention. However, the isCategoryIndex configuration does not affect the document URL.

Use the slug front matter to provide an explicit document URL and override the default one.

For example, suppose your site structure looks like this:

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

By default, hello.md will be available at /docs/guide/hello. You can change its URL location to /docs/bonjour:

---
slug: /bonjour
---

Lorem ipsum

slug will be appended to the doc plugin's routeBasePath, which is /docs by default. See Docs-only mode for how to remove the /docs part from the URL.

备注

It is possible to use:

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

提示

Changing a document's filename or id, will change its default URL. To prevent breaking permalinks when renaming files, we recommend setting an explicit slug to keep your URLs stable.

Making a document available at the root

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

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

Lorem ipsum

侧边栏

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

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

文档前言​

文档标签​

组织文件夹结构​

文档 ID​

文档 URL​

Making a document available at the root​

侧边栏​