Docusaurus 搭建个人知识库

前言

博客是用来展示自己的，想写啥就写啥，所以会比较杂。而 Wiki 更偏向于电子百科，可以作为个人知识库。市面上有很多优秀的 Wiki 系统，但我不想花钱买数据库服务，只能找不需要数据库的这一类系统。因此找到了 Docusaurus ，支持用 jsx 语法的 markdown，无缝结合 React。具体效果可以参考我的 Wiki

Docusaurus 安装

主要参考了官方文档

系统需求

Node.js >= 16.14 或 yarn >= 1.5

创建站点

安装 Docusaurus 的最简单方法是使用命令行工具，该工具会搭建 Docusaurus 网站骨架。

在新的空存储库中或现有存储库中的任何位置运行此命令，将创建一个包含支架文件的新目录，并自动下载安装需要的库。

1
2
3

npx create-docusaurus@latest my-website classic
# `my-website` 为你想要创建的目录，`classic` 为你想要用的模板
# 也可以选择 `facebook`、`bootstrap` 等模板

运行站点

要在编辑文件时预览更改，可以运行一个本地服务器并启动你的网站，最新更改就能立即反映出来了。

1 2	cd my-website npm start

默认情况下，浏览器将打开 http://localhost:3000 网址。

恭喜你！您刚刚创建了第一个 Docusaurus 网站！浏览网站以查看可用内容吧。

配置站点信息

由于我只是想搭建个人知识库，因为已经搭建好了个人博客，所以修改了下 docusaurus.config.js 中的presets，删除了 blog 页面，只保留 Docs

presets: [
  [
    'classic',
    /** @type {import('@docusaurus/preset-classic').Options} */
    ({
      docs: {
        sidebarPath: './sidebars.js',
        // Please change this to your repo.
        // Remove this to remove the "edit this page" links.
        editUrl:
          'https://github.com/FelicxFoster/WikiPage/tree/master',
      },
      theme: {
        customCss: './src/css/custom.css',
      },
    }),
  ],
],

找到 docusaurus.config.js 中的 navbar，注释掉 blog 那一行

navbar: {
  title: 'YOLOのWiki',
  logo: {
    alt: 'YOLOのWiki Logo',
    src: 'img/logo.svg',
  },
  items: [
    {
      type: 'docSidebar',
      sidebarId: 'tutorialSidebar',
      position: 'left',
      label: 'Note',
    },
    // {to: '/blog', label: 'Blog', position: 'left'},
    {
      href: 'https://github.com/FelicxFoster/',
      label: 'GitHub',
      position: 'right',
    },
  ],
},

Docusaurus 部署

Vercel 有个好处，可以自动编译并部署，所以只需要把代码提交到 Github 仓库，并在 Vercel 里 import 该仓库就可以了。

由于每次部署 Vercel 编译需要时间太久，所以尽量在本地调试好再推送到 Vercel。

1 2	npm run build # 编译生成 build 文件 npm run serve # 可视化编译的效果

Docusaurus 美化

搜索插件

Docusaurus 默认是没有搜索功能的，这里使用 docusaurus-search-local 这款本地搜索插件来实现。

插件安装

1	npm i @easyops-cn/docusaurus-search-local

配置

在 docusaurus.config.js 中的 config 内容中新增，与 themeConfig 同级

themes: [
  [
    require.resolve("@easyops-cn/docusaurus-search-local"),
    {
      hashed: true,
      language: ["en", "zh"],
      highlightSearchTermsOnTargetPage: true,
      explicitSearchResultPath: true,
    },
  ],
],

配置完后，可能会报错，显示 Module not found: Error: Can't resolve '@theme/SearchPage'，不用担心，根据 issue，只需要重新 npm start 即可。

语法高亮

Docusaurus 默认使用 prismjs 进行代码块的语法高亮，但是需要自己安装这个库，下面参考Docusaurus 代码块。

库安装

1	npm i prismjs

配置

安装完后，使用 3 个反引号包裹文本块，就可以实现代码块高亮了，比如

1	```js console.log('每个仓库都应该有个吉祥物。'); ```

但是 prismjs 默认只有部分语言可以高亮，像 bash、poweshell 这些，需要在 docusaurus.config.js 中的 prism 内容中新增 additionalLanguages，如下所示，具体要添加的内容，可以在 Supported languages 中查找。

prism: {
  theme: prismThemes.github,
  darkTheme: prismThemes.dracula,
  additionalLanguages: ['Bash'],
},

注意添加了 additionalLanguages，需要重新启动 Docusaurus 才能生效。

emoji 使用

想要在文档中添加 emoji，如📝，需要安装 remark-emoji 库。

库安装

1	npm i remark-emoji

更改字体

Docusaurus 默认字体有点不好看，本站使用霞鹜文楷来替换。

法一

在 releases 下载想要的 ttf 字体（我选的是 LXGWWenKai-Bold.ttf ），放在 Docusaurus 项目的 static/font 目录下。

修改 src/css/custom.css 添加字体，在最前面添加如下内容：

@font-face {
  font-family: 'LXGWWenKai Regular';
  src: url('/font/LXGWWenKai-Regular.ttf');
}

设置 ifm-font-family-base:

:root {
  ...
  --ifm-font-family-base: "LXGWWenKai Regular";
}

保存即可生效。

法二

上面这种方法每次都要在网页端加载 ttf 字体，会导致网页加载很慢。其实我们可以使用 CDN，网页加载时只需获取所使用的文字所在的分包，大幅降低所需加载的大小，从而提升网页加载速度。

参考 lxgw-wenkai-webfont 的使用文档，先安装字体

1	npm install --save lxgw-wenkai-webfont

然后将 CDN 地址添加到 docusaurus.config.js 的 stylesheets 属性（与 themes 配置同一级）

stylesheets: [
  // String format.
  'https://docusaurus.io/style.css',
  // Object format.
  {
    href: 'https://cdn.bootcdn.net/ajax/libs/lxgw-wenkai-webfont/1.7.0/style.min.css',
  },
],

最后像上面一样修改 src/css/custom.css 的 :root 属性（注意和上面的有点区别）

:root {
  ...
  --ifm-font-family-base: "LXGW WenKai";
}