跳到主要内容
版本：Canary 🚧

创建文档

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

website # 你的网站的根目录
├── docs
│   └── greeting.md
├── src
│   └── pages
├── docusaurus.config.js
├── ...
----
description: 创建一个内容丰富的文档页面。
---

## 来自 Docusaurus 的问候

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

## 标题

会显示在右上方的目录

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

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

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

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

- lists will help you
- present the key points
- that you want your users to remember
  - and you may nest them
    - multiple times
备注

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

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

文档前言​

前言是用来为你的文档页面提供额外的元数据的。 前言是可选的——Docusaurus 能够自行推断所有必要的元数据，无需前言。 For example, the doc tags feature introduced below requires using front matter. For all possible fields, see the API documentation.

文档标签​

Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the docs sidebar. 在文档导言中，像这么声明一个标签列表：

---
id: doc-with-tags
title: 一篇包含标签的文档
tags:
  - 演示
  - 开始上手
---
提示

标签也可以用 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, a document's URL location is its file path relative to the docs folder, with a few exceptions. Namely, if a file is named one 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.

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

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

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

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

---
slug: /bonjour
---

Lorem ipsum

slug 会被添加到文档插件的 routeBasePath 后面。routeBasePath 默认是 /docs。 See Docs-only mode for how to remove the /docs part from the URL.

备注

你可以使用：

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

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

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

Lorem ipsum

When using autogenerated sidebars, the file structure will determine the sidebar structure.

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