跳转至主内容
Version: 2.0.0-beta.21 🚧

文档简介

文档功能可让您以层级格式组织编排 Markdown 文件。

信息

阅读文档插件 API 参考文档了解配置选项的完整列表。

文档标识符

每个文档均有唯一的 id (标识符)。 默认情况下,文档 id 是相对根文档目录的文件名称 (除文件名)。

例如,greeting.md 的标识符是 greeting,而 guide/hello.md 的标识符则是 guide/hello

website # Root directory of your site
└── docs
├── greeting.md
└── guide
└── hello.md

However, the last part of the id can be defined by the user in the front matter. 举个例子,如果 guide/hello.md' 的内容为如下所示,其最终的 id 则为 guide/part1

---
id: part1
---

Lorem ipsum

Customizing doc URLs

By default, a document's URL location is its file path relative to the docs folder. Use the slug front matter to change a document's URL.

For example, suppose your site structure looks like this:

website # Root directory of your site
└── docs
└── guide
└── hello.md

By default hello.md will be available at /docs/guide/hello. You can change its URL location to /docs/bonjour:

---
slug: /bonjour
---

Lorem ipsum

slug will be appended to the doc plugin's routeBasePath, which is /docs by default. See Docs-only mode for how to remove the /docs part from the URL.

note

您可以使用:

  • 绝对路径:slug: /mySlugslug: /...
  • 相对路径:slug: mySlugslug: ./../mySlug...

首页文档

If you want a document to be available at the root, and have a path like https://docusaurus.io/docs/, you can use the slug front matter:

---
id: my-home-doc
slug: /
---

Lorem ipsum

仅文档模式

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/.
caution

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

Docusaurus 2 中还存在 ”仅博客模式“。 您可以使用上述的方法切换。 你可以在仅博客模式一节了解如何配置。