跳到主要内容
版本：3.8.1

创建文档

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

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 目录下，所有以_（下划线）开头的文件都将被视为“部分”页面，并默认被忽略。

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

文档 Front Matter​

Front matter 用于为你的文档页面提供额外的元数据。Front matter 是可选的——Docusaurus 可以在没有 front matter 的情况下推断所有必要的元数据。例如，下面介绍的文档标签功能需要使用 front matter。有关所有可能字段，请参阅API 文档。

文档标签​

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

可以直接内联定义标签，也可以引用在标签文件（可选，通常是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: 'Docs related to the Docusaurus framework'
提示

标签也可以通过 tags: [Demo, Getting started] 方式声明。

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

组织文件夹结构​

Markdown 文件在 docs 文件夹下的排列方式可能对 Docusaurus 内容生成产生多方面影响。然而，其中大部分可以与文件结构解耦。

文档 ID​

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

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

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

然而，id 的最后一部分可以在 front matter 中由用户定义。例如，如果 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 段。

注意

此约定与类别索引约定完全相同。然而，isCategoryIndex 配置不会影响文档 URL。

使用 slug front matter 来更改文档的 URL。

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

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

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

---
slug: /bonjour
---

Lorem ipsum

slug 将被附加到文档插件的 routeBasePath（默认为 /docs）。请参阅仅文档模式，了解如何从 URL 中删除 /docs 部分。

注意

可以使用

  • 绝对 slug：slug: /mySlug, slug: /...
  • 相对 slug：slug: mySlug, slug: ./../mySlug...

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

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

Lorem ipsum

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

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