跳到主要内容
版本:Canary 🚧

创建文档

创建名为 greeting.md 的 Markdown 文件,把它放在 docs 目录下。

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

## 来自 Docusaurus 的问候

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

## 标题

会显示在右上方的目录

这样,你的用户不用通读全文就可以知晓这篇文章的主要内容。

## 目录默认只包括 h2 和 h3 标题。

你可以在每个文档或主题配置中设置目录包含的标题层级。

标题会保持恰当的间距,让文章看起来层级清晰。

- 列表将帮助你
- 阐述让用户牢记的关键点
- 你还可以将其嵌套
- 很多次

## 自定义标题 ID {#custom-id}

你可以用 `{#custom-id}` 语法自定义标题 ID。
备注

docs 目录下所有带有下划线(_)前缀的文件都会被当作页面「片段」,并被默认忽略。

你可以阅读更多关于导入页面片段的内容。

文档前言

前言是用来为你的文档页面提供额外的元数据的。 前言是可选的——Docusaurus 能够自行推断所有必要的元数据,无需前言。 比如下面介绍的文档标签功能就需要使用前言。 要了解所有可用的字段,可以访问 API 文档

文档标签

你可以选择性地为你的文档页面添加标签。标签为你的文档引入了侧边栏之外的又一个分类维度。 在文档导言中,像这么声明一个标签列表:

---
id: doc-with-tags
title: 一篇包含标签的文档
tags:
- 演示
- 开始上手
---
提示

标签也可以用 tags: [演示, 开始上手] 的语法定义。

你也可以阅读更多关于所有的 Yaml 数组声明语法的内容。

组织文件夹结构

docs 文件夹下 Markdown 文件的排列可能对 Docusaurus 的内容生成产生多重影响。 然而,其中绝大多数可以与文件结构脱钩。

文档 ID

每个文档均有唯一的 id(标识符)。 默认情况下,文档 id 是文件相对文档根目录的路径(不包括后缀)。

例如,greeting.md 的 ID 是 greeting,而 guide/hello.md 的 ID 则是 guide/hello

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

但是,用户可以在前言中指定 id最后一部分。 举个例子,如果 guide/hello.md 的内容为如下所示,其最终的 id 则为 guide/part1

---
id: part1
---

Lorem ipsum

当手写侧边栏,或这使用与文档相关的布局或钩子时,ID 会被用来指代某篇文档。

文档 URL

文档的 URL 路径默认为它相对于 docs 文件夹的路径。 你可以用 slug 前言来更改文档的 URL。

比如,假设你的网站结构长得像这样:

website # 你的网站的根目录
└── docs
└── guide
└── hello.md

默认情况下,hello.md 可以在 /docs/guide/hello 处访问。 你也可以把它的 URL 位置修改为 /docs/bonjour

---
slug: /bonjour
---

Lorem ipsum

slug 会被添加到文档插件的 routeBasePath 后面。routeBasePath 默认是 /docs。 请参考仅文档模式,了解怎么从 URL 中去掉 /docs 部分。

备注

你可以使用:

  • 绝对路径:slug: /mySlugslug: /...
  • 相对路径:slug: mySlugslug: ./../mySlug...

如果你想要让一篇文档位于网站根部下,有形如 https://docusaurus.io/docs/ 的路径,那么你可以这么填写前言中的 slug:

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

Lorem ipsum

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

我们关于文件系统组织的建议是:让你的文件系统和侧边栏结构保持一致(这样你就不需要手写你的 sidebars.js 文件),并使用 slug 前言来自定义每个文档的 URL。