跳到主要内容
版本：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.

文档标签​

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

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 references a predefined tag key declared in 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: [演示, 开始上手] 的语法定义。

你也可以阅读更多关于所有的 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。