文档介绍

文档功能允许用户以层级格式组织编排 Markdown 文件。

信息

阅读文档插件 API 参考文档了解配置选项的完整列表。

文档 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

自定义文档 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: /mySlug、slug: /...
• 相对路径：slug: mySlug、slug: ./../mySlug...

首页文档

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

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

Lorem ipsum

仅文档模式

新创建的 Docusaurus 网站会有这样的结构：

example.com/                                -> 生成自 `src/pages/index.js`

example.com/docs/intro                      -> 生成自 `docs/intro.md`
example.com/docs/tutorial-basics/...        -> 生成自 `docs/tutorial-basics/...`
...

example.com/blog/2021/08/26/welcome         -> 生成自 `blog/2021-08-26-welcome/index.md`
example.com/blog/2021/08/01/mdx-blog-post   -> 生成自 `blog/2021-08-01-mdx-blog-post.mdx`
...

所有文档都会放在 docs/ 子路由下。 但是如果你的网站只有文档，或者你想要把文档放在网站根部，突出它的重要性呢？

假设你的配置中包含以下内容：

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    '@docusaurus/preset-classic',
    {
      docs: {
        /* 文档插件配置 */
      },
      blog: {
        /* 博客插件配置 */
      },
      // ...
    },
  ],
};

要进入仅文档模式，可以把它改成类似这样：

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    '@docusaurus/preset-classic',
    {
      docs: {
        routeBasePath: '/', // 把文档放在网站根部
        /* 其他文档插件配置 */
      },
      blog: false, // 可选：禁用博客插件
      // ...
    },
  ],
};

注意，你不一定要放弃使用博客或者其他插件。设置 routeBasePath: '/' 所产生的唯一效果就是把文档从 https://example.com/docs/some-doc 移到了网站根部：https://example.com/some-doc。 如果启用了博客，还是可以通过 blog/ 子路由访问到它。

别忘了通过添加前言把某个页面放置在网站顶部 (https://example.com/)：

docs/intro.md

---
slug: /
---

这一页会是用户访问 https://example.com/ 时出现的主页。

注意

如果你用 slug: / 把某篇文档变成了主页，你就需要删掉 src/pages/index.js 的现有首页，否则会有两个文件映射到同一个路径!

现在，网站的结构会长得像这样：

example.com/                       -> 生成自 `docs/intro.md`
example.com/tutorial-basics/...    -> 生成自 `docs/tutorial-basics/...`
...

提示

Docusaurus 2 中还存在 ”仅博客模式“。 你可以用类似上述的方法实现。 你可以在仅博客模式一节了解如何配置。