跳到主要内容
版本:3.5.2

文档介绍

文档功能允许用户以层级格式组织编排 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.