docusaurus简单使用
前言
docusaurus是一款使用markdown编写手册文档的工具，同类竞品有vitePress (放弃不维护的vuepress吧)
目前来看，比后者多了10k个start。
docusaurus是基于react，而vitepress是基于vue的，使用什么取决于 看你技术栈或者要编写文档的内容了。
创建项目
脚手架创建项目，比如我想创建一个名为linux-book的项目
npx create-docusaurus@latest my-website classic
设置默认语言
然后集成i18n，不然上一页下一页 以及基本的语言默认都是英语。
docusaurus帮我们翻译了一些基础的单词，我们去下载语言即可。
下载完成后复制到项目根目录中 my-website/i18n/zh-Hans。
最后在配置文件 docusaurus.config.js 中，添加如下配置即可
{
// 其它配置
// ...
// 本地化语言配置
i18n: {
defaultLocale: "zh-Hans",
locales: ["zh-Hans"],
},
}
基础知识
docusaurus 由几个重要的部分构成：站点元数据、主题、插件、预设，
分别对应其配置文件中的
{
// 站点元数据
title: "前端",
tagline: "前端非常酷",
favicon: "img/favicon.ico",
url: "https://your-docusaurus-site.example.com",
baseUrl: "/",
// 主题、插件、预设
presets: [ ],
plugins: [ ],
themes: [ ]
}
Docusaurus 核心不提供它自己的任何功能。
它将所有功能都委托给了独立插件，如果没有安装插件，站点就不会包含任何路径，比如：
但是，你可能不需要一个一个地安装常用插件：“它们可以作为预设的一部分被打包分发”。 对于大多数用户来说，插件是通过预设选项来配置的。我们有一份官方和社区非官方插件。若你想要添加一些功能功能记得翻翻：或说不定有人可能已经帮你实现好了！
当然，如果你觉得自己很有精力，你也可以阅读插件指南或插件方法总览了解如何自己制作插件。
隐藏md内的标题
其实这个一级标题没啥用，因为左侧菜单不久知道当前讲的是啥了吗
而且如果你不手动设置标题，默认标题去除的是对应md的id，可能不太好看。
所以参考官方文档隐藏标题掉即可，暂时还没找到全局配置隐藏。
---
hide_title: true
关于部署
我这边是部署到gitPage上的，所以需要将docusaurus.config.js中的baseUrl改为如下即可
baseUrl: "/linux-book/build/"
折叠侧边栏
1、侧边栏从2.0开始 支持折叠菜单了。直接建菜单就可以体验效果。
2、默认情况下，折叠菜单中，文件夹就是一级标题，点击标题展开的二级标题，实际上就是目录里的md文件。
3、如果点击折叠菜单的一级标题，不想展开，而是拥有自己的页面，则需要在此目录内新建立一个文件_category_.json，代码如下即可
{
"label": "第2章_规范",
"link": {
"type": "generated-index",
"description": "这一章讲的就是规范"
}
}
还要记得把docusaurus.config.js设置onBrokenLinks: "ignore"，否则编译不通过
4、显然，第3条，仅靠description可能满足不了需求，能不能指定一个markdown文件呢，当然可以
_category_.json修改如下
{
"label": "第2章_规范",
"link": {
"type": "doc",
"id": "第2章_规范/index"
}
}
然后在此目录下创建一个index.md
---
slug: 第2章_规范
---
## 说明
为了保证开发风格和质量，实现较好的可读性和可维护性。
😊 当然还有一个偷懒的办法，以上都不用做，你只需要将 对应文件夹里的某个md文件与文件同名即可。
侧边栏标题
左边侧边栏的栏目和页面内的一级标题，都取的是md文件内定义的title
xxx.md
---
title: 第3章 脚手架
---
如果没有title属性 则默认取之当前文件的id（如果不在文件内声明id，则默认取文件名作为id）
侧边栏排序
多个库/文档（实例）
文档从上到下有四个组织架构：独立页面、侧边栏、版本、插件实例。
单实例
单个文档库（既单实例） 其实是插件 @docusaurus/plugin-content-docs 来帮你实现的。
不过我们平时通过预设 @docusaurus/preset-classic 来配置和使用了这个插件。
{
// 其它配置
// ...
presets: [
[
"classic",
{
docs: {
// 这里其实就是 @docusaurus/plugin-content-docs 的配置项
sidebarPath: require.resolve("./sidebars.js"),
path: "docs/redux",
routeBasePath: "redux",
},
},
],
];
}
需要注意的是，通过预设我们配置的文档，一定被归属于你项目的默认文档实例（ 既插件plugin-content-docs 的实例）。
虽然不管我们有没有配置 的 默认文档实例子配置id，它都为 default。
多实例
多个文档库，其实就是调用了多次 @docusaurus/plugin-content-docs
{
// 其它配置
// ...
presets: [
[
"classic",
{
docs: {
// 默认实例（也是 @docusaurus/plugin-content-docs一个实例）
path: "docs/html",
sidebarPath: "./sidebars.ts",
routeBasePath: "html",
},
},
],
],
plugins: [
[
"@docusaurus/plugin-content-docs",
{
id: "two", // 唯一的 ID，用于标识这一实例
path: "docs/two", // 文档内容路径
routeBasePath: "two", // 路由路径，例如 https://example.com/two
sidebarPath: "./sidebars.ts", // 侧边栏配置
},
],
],
};
多实例优化
以下只是个人觉得：既然是多文档（实例）模式，那我所有的文档都在plugin配置，不和预设相互掺合。
{
presets: [
[
"classic",
{
docs: false, // 预设里不用@docusaurus/plugin-content-docs帮我们创建默认实例
blog: {
showReadingTime: true,
},
theme: {
customCss: "./src/css/custom.css",
},
},
],
],
plugins: [
[
"@docusaurus/plugin-content-docs",
{
id: "default", // 必须是default
path: "docs/html",
routeBasePath: "/html",
sidebarPath: "./sidebars.ts",
},
],
[
"@docusaurus/plugin-content-docs",
{
id: "exam-module",
path: "docs/exam",
routeBasePath: "exam",
sidebarPath: "./sidebars.ts",
},
],
"docusaurus-plugin-sass",
],
};
当然，你甚至可以完全不使用预设 @docusaurus/preset-classic, 这样避免非得配置docs插件。
然后在单独让 @docusaurus/theme-classic主题引入进去。
但是这样默认的主页却不现实了，不知道为啥，其他倒是还好，估计预设做了这些处理，所以综上，我们还是如上做法（docs: false）好使！
顶部导航
这一章，在API>主题 有详细的介绍。
以下记录一个上边代码对应的菜单，既 文档集类型 docSidebar，即导航对应的是 多文档实例
{
navbar: {
// ...
items: [
{
type: "docSidebar", // 导航类型（比如单独页面、文档集（含侧边栏）、折叠栏、超链外接等等）
sidebarId: "tutorialSidebar", // 绑定的侧边栏 在绑定的插件sidebarPath中定义
position: "left", // 位置
label: "网页", // 导航名称
docsPluginId: "default", // 对应的插件ID
},
{
type: "docSidebar",
sidebarId: "tutorialSidebar",
position: "left",
label: "面试",
docsPluginId: "exam-module",
},
],
},
// 其他配置...
};
