跳到主要内容

创建文档

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

website # root directory of your site
├── docs
│   └── greeting.md
├── src
│   └── pages
├── docusaurus.config.js
├── ...
---
description: 创建包含丰富内容的文档页面。
---

# 来自 Docusaurus 的问候

您准备好为您的开源项目创建文档网站了吗？

## 标题

将显示在右上角的目录中

这样您的用户就能知道这个页面的内容，而无需向下滚动或阅读太多内容。

## 默认情况下，只有 h2 和 h3 会出现在目录中。

您可以在每个文档中或在主题配置中配置目录标题级别。

标题间距良好，层次结构清晰。

- 列表将帮助您
- 展示关键要点
- 让您的用户记住
  - 您可以嵌套它们
    - 多次嵌套
备注

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

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

文档前置元数据​

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

文档标签​

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

可以内联定义标签，或引用在标签文件中声明的预定义标签（可选，通常是 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 的最后部分可以由用户在前置元数据中定义。例如，如果 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 前置元数据来更改文档的 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.io/docs/ 的路径，您可以使用 slug 前置元数据：

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

Lorem ipsum

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

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