Skip to main content
Version: 2.x

文档介绍

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

info

查看Docs Plugin API 参考文档以获取完整的选项列表。

您的站点文档按四个层次组织，从低到高依次为：

  1. 单个页面。
  2. 侧边栏。
  3. 版本。
  4. 插件实例。

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

仅文档模式​

一个新初始化的Docusaurus站点具有以下结构：

example.com/                                -> generated from `src/pages/index.js`

example.com/docs/intro                      -> generated from `docs/intro.md`
example.com/docs/tutorial-basics/...        -> generated from `docs/tutorial-basics/...`
...

example.com/blog/2021/08/26/welcome         -> generated from `blog/2021-08-26-welcome/index.md`
example.com/blog/2021/08/01/mdx-blog-post   -> generated from `blog/2021-08-01-mdx-blog-post.mdx`
...

所有文档将在子路由docs/下提供服务。但如果你的网站只有文档，或者你想通过将文档放在根目录来优先处理它们呢？

假设您的配置中有以下内容：

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    '@docusaurus/preset-classic',
    {
      docs: {
        /* docs plugin options */
      },
      blog: {
        /* blog plugin options */
      },
      // ...
    },
  ],
};

要进入仅文档模式，请将其更改为如下所示：

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    '@docusaurus/preset-classic',
    {
      docs: {
        routeBasePath: '/', // Serve the docs at the site's root
        /* other docs plugin options */
      },
      blog: false, // Optional: disable the blog plugin
      // ...
    },
  ],
};

请注意，您不一定需要放弃使用博客或其他插件；routeBasePath: '/'所做的只是将文档从https://example.com/docs/some-doc改为在站点根目录下提供：https://example.com/some-doc。如果启用了博客，仍然可以通过blog/子路由访问。

别忘了在根目录（https://example.com/）下添加一些页面，通过添加前置内容：

docs/intro.md
---
slug: /
---

This page will be the home page when users visit https://example.com/.
warning

如果你在文档中添加了slug: /以使其成为主页，你应该删除现有的主页./src/pages/index.js，否则将有两个文件映射到相同的路由！

现在，网站的结构将如下所示：

example.com/                       -> generated from `docs/intro.md`
example.com/tutorial-basics/...    -> generated from `docs/tutorial-basics/...`
...
tip

对于那些只想使用Docusaurus 2的博客功能的用户，还有一个“仅博客模式”。你可以使用上面详细描述的相同方法。按照仅博客模式上的设置说明进行操作。