跳到主要内容

创建文档

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

website # 你的站点根目录
├── docs
│   └── greeting.md
├── src
│   └── pages
├── docusaurus.config.js
├── ...
---
description: 创建一篇内容丰富的文档页面。
---

# Hello from Docusaurus

你是否已准备好为你的开源项目创建文档网站了呢？

## h2标题
标题会自动出现在右上角的目录中

这样，你的用户无需向下滚动或甚至无需过多阅读，就能了解此页面的全部内容。

## 默认情况下，目录中仅显示 h2 和 h3 标题

你可以为单篇文档或在主题配置中设置目录的标题级别。

标题间距经过精心设计，层次结构清晰分明。

- 列表可以帮助你
- 呈现那些希望用户记住的要点
- 而且你可以对它们进行嵌套
  - 甚至是多层嵌套
备注

在 docs 目录下，所有带下划线（_）前缀的文件都会被视为"局部页面"，并默认被忽略。

进一步了解导入局部页面。

文档 头部元数据（Front Matter）​

头部元数据（Front matter） 用于为你的文档页面提供额外的元数据。Front matter 是可选的——即使没有它，道格龙（Docusaurus）也能推断出所有必要的元数据。例如，下文介绍的文档标签功能就需要使用 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: '与道格龙 (Docusaurus) 框架相关的文档'
提示

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

进一步了解所有可用的 Yaml 数组语法。

组织文件夹结构​

Markdown 文件在 docs 文件夹下的组织方式会对道格龙（Docusaurus）的内容生成产生多方面影响。然而，这些影响大多可以与文件结构解耦。

文档 ID​

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

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

website # 你的站点根目录
└── docs
   ├── greeting.md
   └── guide
      └── hello.md

但是，用户可以在 front matter 中定义 id 的最后一部分。例如，如果 guide/hello.md 的内容如下面所示，其最终 id 就是 guide/part1。

---
id: part1
---

Lorem ipsum

在手动编写侧边栏，或使用与文档相关的布局组件或 hook 时，会使用 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 # 你的站点根目录
└── 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 头部元数据（front matter）：

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

Lorem ipsum

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

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