文档介绍
文档功能允许用户以层级格式组织编排 Markdown 文件。
阅读文档插件 API 参考文档了解配置选项的完整列表。
文档 ID
每个文档均有唯一的 id
(标识符)。 默认情况下,文档 id
是文件相对文档根目录的路径(不包括后缀)。
例如,greeting.md
的 ID 是 greeting
,而 guide/hello.md
的 ID 则是 guide/hello
。
website # 你的网站的根目录
└── docs
├── greeting.md
└── guide
└── hello.md
但是,用户可以在前言中指定 id
的最后一部分。 举个例子,如果 guide/hello.md
的内容为如下所示,其最终的 id
则为 guide/part1
。
---
id: part1
---
Lorem ipsum
自定义文档 URL
文档的 URL 路径默认为它相对于 docs
文件夹的路径。 你可以用 slug
前言来更改文档的 URL。
比如,假设你的网站结构长得像这样:
website # 你的网站的根目录
└── docs
└── guide
└── hello.md
默认情况下,hello.md
可以在 /docs/guide/hello
处访问。 你也可以把它的 URL 位置修改为 /docs/bonjour
:
---
slug: /bonjour
---
Lorem ipsum
slug
会被添加到文档插件的 routeBasePath
后面。routeBasePath
默认是 /docs
。 请参考仅文档模式,了解怎么从 URL 中去掉 /docs
部分。
你可以使用:
- 绝对路径:
slug: /mySlug
、slug: /
... - 相对路径:
slug: mySlug
、slug: ./../mySlug
...
首页文档
如果你想要让一篇文档位于网站根部下,有形如 https://docusaurus.io/docs/
的路径,那么你可以这么填写前言中的 slug:
---
id: my-home-doc
slug: /
---
Lorem ipsum
仅文档模式
新创建的 Docusaurus 网站会有这样的结构:
example.com/ -> 生成自 `src/pages/index.js`
example.com/docs/intro -> 生成自 `docs/intro.md`
example.com/docs/tutorial-basics/... -> 生成自 `docs/tutorial-basics/...`
...
example.com/blog/2021/08/26/welcome -> 生成自 `blog/2021-08-26-welcome/index.md`
example.com/blog/2021/08/01/mdx-blog-post -> 生成自 `blog/2021-08-01-mdx-blog-post.mdx`
...
所有文档都会放在 docs/
子路由下。 但是如果你的网站只有文档,或者你想要把文档放在网站根部,突出它的重要性呢?
假设你的配置中包含以下内容:
module.exports = {
// ...
presets: [
'@docusaurus/preset-classic',
{
docs: {
/* 文档插件配置 */
},
blog: {
/* 博客插件配置 */
},
// ...
},
],
};
要进入仅文档模式,可以把它改成类似这样:
module.exports = {
// ...
presets: [
'@docusaurus/preset-classic',
{
docs: {
routeBasePath: '/', // 把文档放在网站根部
/* 其他文档插件配置 */
},
blog: false, // 可选:禁用博客插件
// ...
},
],
};
注意,你不一定要放弃使用博客或者其他插件。设置 routeBasePath: '/'
所产生的唯一效果就是把文档从 https://example.com/docs/some-doc
移到了网站根部:https://example.com/some-doc
。 如果启用了博客,还是可以通过 blog/
子路由访问到它。
别忘了通过添加前言把某个页面放置在网站顶部 (https://example.com/
):
---
slug: /
---
这一页会是用户访问 https://example.com/ 时出现的主页。
如果你用 slug: /
把某篇文档变成了主页,你就需要删掉 src/pages/index.js
的现有首页,否则会有两个文件映射到同一个路径!
现在,网站的结构会长得像这样:
example.com/ -> 生成自 `docs/intro.md`
example.com/tutorial-basics/... -> 生成自 `docs/tutorial-basics/...`
...
Docusaurus 2 中还存在 ”仅博客模式“。 你可以用类似上述的方法实现。 你可以在仅博客模式一节了解如何配置。