Version: 3.6.1

文档简介

¥Docs Introduction

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

¥The docs feature provides users with a way to organize Markdown files in a hierarchical format.

信息

检查文档插件 API 参考文档以获得详尽的选项列表。

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

你站点的文档按四个级别进行组织，从最低到最高：

¥Your site's documentation is organized by four levels, from lowest to highest:

单独的页面。

¥Individual pages.
侧边栏。

¥Sidebars.
版本。

¥Versions.
插件实例。

¥Plugin instances.

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

¥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 站点具有以下结构：

¥A freshly initialized Docusaurus site has the following structure:

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/ 下提供。但是，如果你的网站只有文档，或者你想通过将文档放在根目录来确定文档的优先级，该怎么办？

¥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?

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

¥Assume that you have the following in your configuration:

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

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

¥To enter docs-only mode, change it to like this:

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

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

¥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.

不要忘记通过添加前面的内容将某些页面放在根目录（https://example.com/）：

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

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

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

警告

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

¥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!

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

¥Now, the site's structure will be like the following:

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

提示

对于那些只想使用 Docusaurus 博客功能的人来说，还有 "仅博客模式"。你可以使用上面详述的相同方法。按照纯博客模式上的设置说明进行操作。

¥There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus. You can use the same method detailed above. Follow the setup instructions on Blog-only mode.

仅文档模式​

仅文档模式