跳到主要内容

文档功能简介

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

信息

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:

  1. Individual pages.
  2. Sidebars.
  3. Versions.
  4. 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.

仅文档展示模式

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

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
module.exports = {
// ...
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
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
// ...
},
],
};

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: /
---

This page will be the home page when users visit 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!

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 2 的博客功能的用户,可以使用“仅博客模式(blog-only mode)”。用法与上面的“仅文档模式(docs-only-mode)”类似。请参考 仅博客模式 的设置说明。