文档介绍

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

信息

Check the Docs Plugin API Reference documentation for an exhaustive list of options.

你的网站的文档从低到高有四层组织架构：

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

The guide will introduce them in that order: starting from how individual pages can be configured, to how to create a sidebar or multiple ones, to how to create and manage versions, to how to use multiple docs plugin instances.

Docs-only mode

新创建的 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`
...

All docs will be served under the subroute docs/. But what if your site only has docs, or you want to prioritize your docs by putting them at the root?

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

docusaurus.config.js

export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          /* docs plugin options */
        },
        blog: {
          /* blog plugin options */
        },
        // ...
      },
    ],
  ],
};

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

docusaurus.config.js

export default {
  // ...
  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
        // ...
      },
    ],
  ],
};

Note that you don't necessarily have to give up on using the blog or other plugins; all that routeBasePath: '/' does is that instead of serving the docs through https://example.com/docs/some-doc, they are now at the site root: https://example.com/some-doc. The blog, if enabled, can still be accessed through the blog/ subroute.

Don't forget to put some page at the root (https://example.com/) through adding the front matter:

docs/intro.md

---
slug: /
---

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

警告

If you added slug: / to a doc to make it the homepage, you should delete the existing homepage at ./src/pages/index.js, or else there will be two files mapping to the same route!

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

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

提示

There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus. 你可以用类似上述的方法实现。 Follow the setup instructions on Blog-only mode.