依托 Material for MkDocs 构建网站

期待顺利打造出 DangalDB 存储引擎，并将其送入开放原子开源基金会孵化。

前言

感谢开放原子开源基金会的张凯老师，他精心制作的文档网站给了我非常大的启发，不过总是依托 Docusaurus 这款优秀的软件来做东西，无异于把同样的事情重复多次，对于自己的水平提升，毫无意义，因此我决定换一款软件来做文档网站（用于 DangalDB，我计划在考研期间，也不放松开源存储引擎的打造），经过一番搜索以后，使用 Material 的 MkDocs 走入我的选择中，原因如下：

1. 部署过程便利 ... 这里我指的是完整的建站方案（如果是单论软件，几款软件的指令是大差不差的，都是 create serve build 几条），现在 Hugo 的许多建站方案，总是有着许多莫名其妙的问题（比如 Hugo-BootStrap 不知道为什么，现在安装就是没有办法成功，不过这让我领悟到，一个稳定的软件供应链是多么重要）。
2. 功能完善 ... 作为开源软件社区的组织者，我希望所有的队友们都可以便利地阅读软件的文档以及编写文档，而不用被很多奇怪的事情困扰（我们要把精力集中在重要的事情上面）。
3. 轻量级 ... 我希望我的文档库不要再出现一百多 MB 的额外依赖。而 MkDocs 结合 Material 整体不过 6M 上下，而且都是使用常用的包管理软件（如 Python pip 安装 Material 主题， Ubuntu apt 安装 mkdocs），不会再向使用 npm 的 Docusaurus 一样，随便下出一百多个软件包来。

安装过程

首先，得安装出 mkdocs 来，假定你在 Ubuntu 系统下面：

sudo apt install mkdocs

然后，配备 pip 软件，它是 Python 的包管理器。

sudo apt install pip

最好将其设置为国内镜像，不然你会很不舒服的（参考 https://mirrors.tuna.tsinghua.edu.cn/help/pypi/ ， 感谢清华大学开源小组的同志们，解决了我们很多麻烦）：

pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

安装 Material 主题：

pip install mkdocs-material

在这里，可能会出现一个名为 error: externally-managed-environment 的错误来，如图：

它的内涵是 Python 希望包的安装不要干扰到系统本身的已有软件包（依赖关系一旦被破坏，容易出问题，这让我想到 PikiwiDB 为了一个稳定的表现，直接把各个软件包的版本都写死这个事），不过一般影响其实不是很多，我们可以加上 --break-system-packages 这条选项，把安装工作推进下去（这个选项的内涵：我们接受可能破坏依赖的结果，不过因为 mkdocs-material 就是一个主题，影响其实很小，几乎没有，所以尽管放心）。

创建一个 MkDocs 网站

首先你需要使用 MkDocs：

# 在当前文件夹创建新网站
mkdocs new .

之后操作 mkdocs.yml 这个文件，它负责指导 MkDocs 的构建行为：

theme:
  name: material

（加上一句这样的话）

最后，使用 mkdocs serve 看一看结果，如果一切顺利的话，如下所示：

（页面，你可以发现非常美观，非常优雅）

（命令行结果）

写在最后

感谢开放原子开源基金会的张凯老师，他的文档工作值得肯定。谢谢 360 基础架构部的原部长于雨老师，他给了我一次打造工业级产品网站 的机会（www.pikiwidb.com 就是我的作品）。

谢谢我的本科生导师，袁国铭教授，我在开源界的成长离不开袁老师的指导。