跳到主要内容
版本：3.10.1

创建文档

创建一个叫做 greeting.md 的 markdown 文件，并且把它放到 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 目录下所有带有下划线（_）前缀的文件都会被当作页面“片段”，并被默认忽略。

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

文档前言​

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

文档标签​

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

可以内联定义标签，也可以引用在标签文件（可选，通常为 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, 入门] 来声明。

进一步了解所有可能的 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 位置派生自文档 id，而该 id 又基于文档的文件路径。

如果文件命名为以下之一，那么该文件名将不会包含在 URL 中：

  • Named as index (case-insensitive): docs/Guides/index.md
  • Named as README (case-insensitive): docs/Guides/README.mdx
  • Same name as parent folder: docs/Guides/Guides.md

在所有情况下，默认的 slug 都只会是 /Guides，不包含 /index、/README 或重复的 /Guides 段。

备注

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

使用 slug 前置元数据来提供显式的文档 URL 并覆盖默认的 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: /mySlug、slug: /……
  • 相对路径标识：slug: mySlug、slug: ./../mySlug……
提示

更改文档的文件名或 id 将改变其默认 URL。 为防止重命名文件时固定链接失效，建议设置明确的 slug 以保持网址稳定。

在根目录下提供文档​

如果您希望文档在根路径下可用，并具有类似 https://docusaurus.io/docs/ 的路径，您可以使用 slug 前置元数据：

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

Lorem ipsum

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

我们推荐的文件系统组织方式是：让你的文件系统与侧边栏结构保持一致（这样你就不需要手动编写 sidebars.js 文件），并使用 slug 前置元数据来自定义每个文档的 URL。