文档介绍

文档功能为用户提供了一种以分层格式组织 Markdown 文件的方式。

信息

您站点的文档由四个层级组织，从最低到最高：

单个页面。
侧边栏。
版本。
插件实例。

本指南将按照这个顺序介绍它们：从如何配置单个页面，到如何创建一个或多个侧边栏，到如何创建和管理版本，再到如何使用多个文档插件实例。

仅文档模式

一个新初始化的 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
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          /* 文档插件选项 */
        },
        blog: {
          /* 博客插件选项 */
        },
        // ...
      },
    ],
  ],
};

要进入仅文档模式，请按如下方式更改：

docusaurus.config.js
export default {
  // ...
  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 博客功能的人，还有一个"仅博客模式"。您可以使用上面详细介绍的相同方法。请按照仅博客模式的设置说明进行操作。

仅文档模式​

仅文档模式