第5章 创建文档

第2.x版：创建文档 新建一个 Markdown 文件 greeting.md，并将其放在 docs 目录下。 website # 网站根目录
├── docs
│ └── greeting.md
├── src
│ └── pages
├── docusaurus.config.js
├── ...
---
description: 创建包含丰富内容的文档页面。
---

# 来自 Docusaurus 的问候

准备为你的开源项目搭建文档站点了吗？

## 标题

会显示在右上角的目录中

让用户无需向下滚动或细读，就能迅速了解页面主题。

## 默认情况下，目录仅包含 h2 和 h3 级别。

你可以在单篇文档中或通过主题配置来调整目录的标题层级。

标题间距经过优化，层级结构一目了然。

- 列表有助于你
- 呈现核心要点
- 确保用户能够牢记
- 还可以嵌套列表
- 支持多层嵌套
注意：docs 目录下所有以下划线（_）开头的文件会被视为“片段”页面，默认会被忽略。了解更多关于导入片段页面的内容。 文档元数据 元数据用于为文档页面提供额外的信息。该部分是可选的——即便没有元数据，Docusaurus 也能自动推断出所有必要的信息。例如，下文介绍的文档标签功能就需要使用元数据。如需查看所有可用字段，请参阅 API 文档。 文档标签 你可以选择为文档页面添加标签，这在侧边栏目录之外增加了另一个分类维度。标签在元数据中以标签列表的形式传入： ---
id: doc-with-tags
title: 带标签的文档
tags:
- Demo
- 入门指南
---
提示：标签也可以写成 tags: [Demo, 入门指南]。了解更多关于 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
不过，id 的最后一段可以由用户在 front matter 中定义。例如，如果 guide/hello.md 的内容如下，则其最终的 id 为 guide/part1。 ---
id: part1
---

Lorem ipsum
当手动编写侧边栏，或使用与 docs 相关的布局组件或 hooks 时，会使用 ID 来引用文档。 文档 URL​ 默认情况下，文档的 URL 路径是相对于 docs 目录的文件路径。你可以使用 slug front matter 来更改文档的 URL。 假设你的网站结构如下： website # Root directory of your site
└── docs
└── guide
└── hello.md
默认情况下，hello.md 可在 /docs/guide/hello 访问。你可以将其 URL 路径更改为 /docs/bonjour： ---
slug: /bonjour
---

Lorem ipsum
slug 会拼接到 doc 插件的 routeBasePath 上，默认值为 /docs。关于如何从 URL 中移除 /docs 部分，请参阅 Docs-only mode。 note：可以使用： 绝对路径 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。