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 核心不提供它自己的任何功能。

它将所有功能都委托给了独立插件，如果没有安装插件，站点就不会包含任何路径，比如：

• 文档功能由文档插件 @docusaurus/plugin-content-docs 提供；
• 独立页面功能由页面插件提供。
• 博客功能由博客插件提供；

但是，你可能不需要一个一个地安装常用插件：“它们可以作为预设的一部分被打包分发”。 对于大多数用户来说，插件是通过预设选项来配置的。我们有一份官方和社区非官方插件。若你想要添加一些功能功能记得翻翻：或说不定有人可能已经帮你实现好了！

当然，如果你觉得自己很有精力，你也可以阅读插件指南或插件方法总览了解如何自己制作插件。

隐藏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章_规范
---

## 说明
![tu](/img/1-1.png)
为了保证开发风格和质量，实现较好的可读性和可维护性。

当然还有一个偷懒的办法，以上都不用做，你只需要将 对应文件夹里的某个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",
      },
    ],
  },
  // 其他配置...
};