文档介绍
文档功能允许用户以层级格式组织编排 Markdown 文件。
信息
查看Docs插件API参考文档获取详细的选项列表。
你的网站的文档从低到高有四层组织架构:
- 独立页面。
- 侧边栏。
- 版本。
- 插件实例。
指南将按这个顺序介绍它们:如何配置单个页面,如何创建侧边栏或多个, 如何创建和管理版本, 如何使用多个Docs插件实例。
仅文档模式
新创建的 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/
子路由下。 但是如果您的网站只有文档,或者您想要将文档放在根目录上来优先排序。
假设你的配置中包含以下内容:
docusaurus.config.js
module.exports = {
// ...
presets: [
'@docusaurus/preset-classic',
{
docs: {
/* 文档插件配置 */
},
blog: {
/* 博客插件配置 */
},
// ...
},
],
};
要进入仅文档模式,可以把它改成类似这样:
docusaurus.config.js
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/
):
docs/intro.md
---
slug: /
---
这一页会是用户访问 https://example.com/ 时出现的主页。
注意
如果你用 slug: /
把某篇文档变成了主页,你就需要删掉 src/pages/index.js
的现有首页,否则会有两个文件会映射到同一个路径!
现在,网站的结构会长得像这样:
example.com/ - 生成自 `docs/intro.md`
example.com/tutorial-basics/... - 生成自 `docs/tutorial-basics/...`
...
提示
Docusaurus 2 中还存在 ”仅博客模式“。 你可以用类似上述的方法实现。 遵循仅博客模式上的设置说明。