文档功能介绍

文档功能为用户提供了一种按层级结构组织 Markdown 文件的方式。

信息

要了解全部选项的详尽列表，请查阅文档插件 API 参考文档。

你的网站文档由四个层级构成，从低到高依次是：

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

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

纯文档模式

一个新初始化的道格龙（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: {
          // 文档插件选项配置
          // 这里可以设置文档插件的各种选项，例如文档的根路径、版本控制等。
          // 具体选项可以参考 Docusaurus 文档插件的 API 参考文档。
        },
        blog: {
          // 博客插件选项配置
          // 这里可以设置博客插件的各种选项，例如博客的根路径、分类等。
          // 具体选项可以参考 Docusaurus 博客插件的 API 参考文档。
        },
        // ...
      },
    ],
  ],
};

要进入纯文档模式，请按如下方式修改配置：

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          routeBasePath: '/', // 在站点根路径下提供文档服务
          /* other docs plugin options */
        },
        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）还有一个"纯博客模式"，专为那些只想使用其博客功能的用户设计。你可以使用上述相同的方法进行设置。请遵循纯博客模式中的设置说明。

纯文档模式​

纯文档模式