docusaurus简单使用

前言

docusaurus是一款使用markdown编写手册文档的工具，同类竞品有vuepress
目前来看，比后者多了10k个start

docusaurus是基于react，而vuepress是基于vue的

官方文档点击此处

使用

创建项目

脚手架创建项目，比如我想创建一个名为linux-book的项目

npx create-docusaurus@latest linux-book classic

设置默认语言

然后集成i18n，不然上一页下一页 以及基本的语言默认都是英语。
docusaurus帮我们翻译了一些基础的单词，我们去下载语言即可。
下载完成后复制到项目根目录中 linux-book/i18n/zh-Hans

修改配置文件

docusaurus.config.js
配置i18n、配置顶部导航、底部、控制生成菜单名字和顺序等等基本信息

// @ts-check

const lightCodeTheme = require("prism-react-renderer/themes/github");
const darkCodeTheme = require("prism-react-renderer/themes/dracula");

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: "linux手册",
  tagline: "学它，你就可以干掉运维",
  url: "https://your-docusaurus-test-site.com",
  baseUrl: "/",
  onBrokenLinks: "throw",
  onBrokenMarkdownLinks: "warn",
  favicon: "img/favicon.ico",
  organizationName: "facebook", // Usually your GitHub org/user name.
  projectName: "linux-book", // Usually your repo name.

  i18n: {
    // 国际化配置
    defaultLocale: "zh",
    locales: ["zh"],
  },

  presets: [
    // 预设
    [
      "classic",
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve("./sidebars.js"),
        },
        theme: {
          customCss: require.resolve("./src/css/custom.css"),
        },
      }),
    ],
  ],

  themeConfig: // 顶部导航和底部导航基础配置
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        title: "linux手册",
        logo: {
          alt: "My Site Logo",
          src: "img/logo.png",
        },
        items: [
          {
            type: "doc",
            docId: "第1章_什么是linux",
            position: "left",
            label: "文档",
          },
          {
            href: "https://www.cnblogs.com/dingshaohua",
            label: "博客",
            position: "right",
          },
        ],
      },
      prism: {
        theme: lightCodeTheme,
        darkTheme: darkCodeTheme,
        defaultLanguage: "javascript",
      },
    }),
};

module.exports = config;

然后完事。

隐藏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文件内定义的title
xxx.md

---
title: 第3章 脚手架
---

如果没有title属性 则默认取之当前文件的id（如果不在文件内声明id，则默认取文件名作为id）

关于侧边栏---排序

除了自定义拦截生成规则，你还可以使用元素据的方式来干涉排序

多个库（实例）

修改配置文件里的两个字段即可
presets.docs里放第一个库实例，新增plugins字段放第二个库实例，具体如下

// @ts-check
const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: '丁少华的个人网站',
  tagline: '这个网站很酷啊，赶紧收藏吧！',
  url: 'https://your-docusaurus-test-site.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'facebook', // Usually your GitHub org/user name.
  projectName: 'docusaurus', // Usually your repo name.
  i18n: {
    defaultLocale: 'zh',
    locales: ['zh'],
  },
  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          path: 'docs/redux',
          routeBasePath: 'redux',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],
  ],

  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'life',
        path: 'docs/life',
        routeBasePath: 'life',
        sidebarPath: require.resolve('./sidebars.js')
      },
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        title: '丁少华的个人网站',
        logo: {
          alt: 'My Site Logo',
          src: 'img/logo.svg',
        },
        items: [
          {
            type: 'doc',
            docId: '1、前言',
            label: 'redux',
          },
          {
            docsPluginId:'life',
            type: 'doc',
            docId: '认识我',
            label: '碎碎念',
          }
        ],
      },
      prism: {
        theme: lightCodeTheme,
        darkTheme: darkCodeTheme,
      },
    }),
};

module.exports = config;