Skip to main content
Version: 3.7.0

创建一个文档

创建一个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
note

所有在docs目录下以下划线（_）为前缀的文件被视为“部分”页面，默认情况下将被忽略。

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

文档前言​

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

文档标签​

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

可以内联定义标签，或者引用在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: 'Docs related to the Docusaurus framework'
tip

标签也可以通过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的最后部分可以由用户在前言中定义。例如，如果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部分。

note

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

使用slug前置内容来更改文档的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 部分。

note

可以使用：

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

如果你希望文档在根目录下可用，并且路径类似于 https://docusaurus.io/docs/，你可以使用 slug front matter：

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

Lorem ipsum

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

我们对于文件系统组织的建议是：使您的文件系统反映侧边栏结构（这样您就不需要手动编写sidebars.js文件），并使用slug前置元数据来自定义每个文档的URL。