跳到主要内容

创建文档

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

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

# 来自 Docusaurus 的问候

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

## 标题

会在右上角的内容目录中显示

这样你的用户就能知道这个页面是关于什么的，而无需向下滚动，甚至无需阅读太多内容。

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

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

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

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

docs 目录下所有以下划线 (_) 开头的文件都被视为“部分”页面，默认情况下会被忽略。

阅读更多关于 导入部分页面 的内容。

文档前置 matter​

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

文档标签​

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

可以内联定义标签，也可以引用在 tags 文件 中声明的预定义标签（可选，通常为 docs/tags.yml）。

在以下示例中：

  • docusaurus 引用在 docs/tags.yml 中声明的预定义标签键
  • Releases 是一个内联标签，因为它不存在于 docs/tags.yml 中
docs/my-doc.md
---
tags:
  - Releases
  - docusaurus
---

# 标题

内容
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 是相对于根 docs 目录的文档名称（不带扩展名）。

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

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

但是，id 的 最后一部分 可以在 front matter 中由用户定义。例如，如果 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 front matter 来更改文档的 URL。

例如，假设您的网站结构如下所示：

网站 # 网站的根目录
└── 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。

编辑此页
最后由 HomeUbuntu 于 更新