创建文档

¥Create a doc

创建一个 Markdown 文件 greeting.md，并将其放在 docs 目录下。

¥Create a Markdown file, greeting.md, and place it under the docs directory.

website # root directory of your site
├── docs
│   └── greeting.md
├── src
│   └── pages
├── docusaurus.config.js
├── ...

---
description: Create a doc page with rich content.
---

# Hello from Docusaurus

Are you ready to create the documentation site for your open source project?

## Headers

will show up on the table of contents on the upper right

So that your users will know what this page is all about without scrolling down or even without reading too much.

## Only h2 and h3 will be in the TOC by default.

You can configure the TOC heading levels either per-document or in the theme configuration.

The headers are well-spaced so that the hierarchy is clear.

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

注意

docs 目录下所有带有下划线（_）前缀的文件都被视为 "partial" 页面，默认会被忽略。

¥All files prefixed with an underscore (_) under the docs directory are treated as "partial" pages and will be ignored by default.

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

¥Read more about importing partial pages.

文档前题

¥Doc front matter

头条新闻 用于为你的文档页面提供附加元数据。前面的内容是可选的 - Docusaurus 将能够在没有前面的内容的情况下推断出所有必要的元数据。例如，下面介绍的 文档标签 功能需要使用 Front Matter。对于所有可能的字段，请参阅 API 文档。

¥The front matter is used to provide additional metadata for your doc page. Front matter is optional—Docusaurus will be able to infer all necessary metadata without the front matter. For example, the doc tags feature introduced below requires using front matter. For all possible fields, see the API documentation.

文档标签

¥Doc tags

标签在前言中声明，除了 文档侧边栏 之外，还引入了另一个分类维度。

¥Tags are declared in the front matter and introduce another dimension of categorization in addition to the docs sidebar.

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

¥It is possible to define tags inline, or to reference predefined tags declared in a tags file (optional, usually docs/tags.yml).

以下示例：

¥In the following example:

• docusaurus 引用了在 docs/tags.yml 中声明的预定义标签键

  ¥docusaurus references a predefined tag key declared in docs/tags.yml

• Releases 是一个内联标签，因为它在 docs/tags.yml 中不存在

  ¥Releases is an inline tag, because it does not exist in docs/tags.yml

docs/my-doc.md

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

# Title

Content

docs/tags.yml

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

提示

标签也可以用 tags: [Demo, Getting started] 声明。

¥Tags can also be declared with tags: [Demo, Getting started].

详细了解所有可能的 Yaml 数组语法。

¥Read more about all the possible Yaml array syntaxes.

组织文件夹结构

¥Organizing folder structure

Markdown 文件在 docs 文件夹下的排列方式会对 Docusaurus 内容生成产生多重影响。然而，它们中的大多数都可以与文件结构解耦。

¥How the Markdown files are arranged under the docs folder can have multiple impacts on Docusaurus content generation. However, most of them can be decoupled from the file structure.

文件编号

¥Document ID

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

¥Every document has a unique id. By default, a document id is the name of the document (without the extension) relative to the root docs directory.

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

¥For example, the ID of greeting.md is greeting, and the ID of guide/hello.md is guide/hello.

website # Root directory of your site
└── docs
   ├── greeting.md
   └── guide
      └── hello.md

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

¥However, the last part of the id can be defined by the user in the front matter. For example, if guide/hello.md's content is defined as below, its final id is guide/part1.

---
id: part1
---

Lorem ipsum

ID 用于在手写侧边栏或使用与文档相关的布局组件或钩子时引用文档。

¥The ID is used to refer to a document when hand-writing sidebars, or when using docs-related layout components or hooks.

文档 URL

¥Doc URLs

默认情况下，文档的 URL 位置是相对于 docs 文件夹的文件路径，但也有一些例外。也就是说，如果文件被命名为以下之一，则该文件名将不会包含在 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

  ¥Named as index (case-insensitive): docs/Guides/index.md

• 命名为 README（不区分大小写）：docs/Guides/README.mdx

  ¥Named as README (case-insensitive): docs/Guides/README.mdx

• 与父文件夹同名：docs/Guides/Guides.md

  ¥Same name as parent folder: docs/Guides/Guides.md

在所有情况下，默认段只有 /Guides，没有 /index、/README 或重复的 /Guides 段。

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

注意

这个约定与 类别索引约定 完全相同。但是，isCategoryIndex 配置不会影响文档 URL。

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

使用 slug 前面的内容更改文档的 URL。

¥Use the slug front matter to change a document's URL.

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

¥For example, suppose your site structure looks like this:

website # Root directory of your site
└── docs
    └── guide
        └── hello.md

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

¥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 将附加到文档插件的 routeBasePath 中，默认情况下为 /docs。请参阅 仅文档模式 了解如何从 URL 中删除 /docs 部分。

¥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: /……

  ¥absolute slugs: slug: /mySlug, slug: /...

• 相对蛞蝓：slug: mySlug、slug: ./../mySlug……

  ¥relative slugs: slug: mySlug, slug: ./../mySlug...

如果你希望文档在根目录下可用，并且具有类似 https://docusaurus.nodejs.cn/docs/ 的路径，则可以使用 slug front Matter：

¥If you want a document to be available at the root, and have a path like https://docusaurus.nodejs.cn/docs/, you can use the slug front matter:

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

Lorem ipsum

侧边栏

¥Sidebars

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

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

我们对文件系统组织的建议是：让你的文件系统镜像侧边栏结构（这样你就不需要手写你的 sidebars.js 文件），并使用 slug 前面的内容来自定义每个文档的 URL。

¥Our recommendation for file system organization is: make your file system mirror the sidebar structure (so you don't need to handwrite your sidebars.js file), and use the slug front matter to customize URLs of each document.