Mkdocs入门

2021-10-02 2991 words 6 minutes

Contents

MkDocs的简单介绍

MkDocs（Markdown Documents）是一个快速、简单的静态网站生成器，用于将 Markdown 文档组织起来构建成有层次、美观的文档站点。

MkDocs 基于 Python 编写，也贯彻了 Python 里「简洁胜于复杂」的理念，与其他常见的静态网站生成器相比，无需繁琐的环境配置（如 Jekyll 涉及的 Bundler、Gems 等），所有配置都用只有简单的一个配置文件管理，并且当中配置项的内容也仅有一页文档。

安装前准备

MkDocs通过python的pip包管理工具进行安装，在安装前检查python和pip安装情况

检查python和pip版本

主流的Linux系统都默认安装了python，但不一定安装了pip，以下仅以Deepin系统为例

首先检查python版本，python有两个版本，一个是python2，目前版本停留在2.7，已经不再更新，另一个是python3，也就是当前我们所熟知的python。两者间有很大的差异，为方便区分，在代码中通常使用python3来调用python。

在终端输入python并回车，可以看到版本号显示的是python 2.7.16，这表明当前查询到的是python2的版本号

1
2
3
4
5
logic@logic-PC:~$ python
Python 2.7.16 (default, Feb 26 2021, 06:12:30) 
[GCC 8.3.0] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> 

按Ctrl+Z退出python2，在终端输入python3并回车，查询python3的版本，显示当前版本为python 3.7.3

1
2
3
4
5
logic@logic-PC:~$ python3
Python 3.7.3 (default, Apr  2 2021, 05:20:44) 
[GCC 8.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

接下来检查pip的安装，退出python3，在终端输入pip --version，显示版本为pip 21.2.4，并标明通过python 3.7安装

1
2
logic@logic-PC:~$ pip --version
pip 21.2.4 from /usr/local/lib/python3.7/dist-packages/pip (python 3.7)

pip的安装

Deepin系统默认是没有安装pip的，pip安装方法如下

首先下载pip的安装脚本

1
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py

接着使用python执行脚本即可

1
sudo python3 get-pip.py

部分 Linux 发行版可直接用包管理器安装 pip，如 Debian 和 Ubuntu

1
sudo apt-get install python-pip

安装完成后在终端输入pip --version查看是否安装成功

MkDocs安装及初始化

安装MkDocs

MkDocs安装非常简单，只须执行

1
2
3
pip install mkdocs 
#请注意，本机只安装了python3的pip包管理器，因此pip默认调用的是pip3，若你的电脑同时安装了python2的pip，则应使用以下命令
pip3 install mkdocs

MkDocs新建站点

按照官网的教程，在本地使用 mkdocs new <your-site-project-name> 即可新建站点项目，但是，MkDocs安装的目录不在Deepin的环境变量中，使得系统无法识别mkdocs这个命令，因此我们须要通过软链接将mkdocs添加到环境变量/usr/local/bin中

首先找到mkdocs所在位置，一般在/<用户主目录>/.local/bin目录下，.local文件夹是隐藏文件夹，需要在文件管理器的设置中选择显示隐藏文件才能看到，因此创建软链接

1
sudo ln -s /home/logic/.local/bin/mkdocs /usr/local/bin/mkdocs

完成之后，即可在/usr/local/bin目录中看到对应的链接文件了，

接下来就可以按官网教程来了，比如我的项目目录叫 mydocs，则新建项目

1
mkdocs new mydocs

执行完成后会在用户主目录下生成项目文件夹mydocs，可以看到项目文件夹内包含一个 docs 文件夹并包含一个名为 index.md 的 Markdown 文件；同时还有一个名为 mkdocs.yml 的文件。

docs 文件夹就是用于存放我们所有的 Markdown 格式的文档内容，当然我们也可根据自己的需要进一步用文件夹归类划分，这也是 MkDocs 运行时默认的根路径。我们也可以后续手动指定修改成其他目录。
mkdocs.yml 该文件主要用于 MkDocs 的定制化配置的设置与管理。
docs/index.md 该文档内容是必须要有的，它是整个 MkDocs 构建的首页入口

使用mkdocs serve即可在本地预览MkDocs渲染的效果

1
2
cd /home/logic/mydocs #进入之前新建的项目文件夹中
mkdocs serve

根据命令提示，浏览器访问127.0.0.1:8000或者localhost:8000即可预览效果

MkDocs 也存在许多可选配置，需要通过 mkdocs.yml 这一个 YAML 文件来进行设置和管理。因此我们需要简单了解一下 YAML 以及如何编写 YAML 文件。

添加站点信息（本地运行无需修改配置）

最开始在 mkdocs.yml 文件中填写的主要还是关于站点相关的信息。其中我们可以填写的有那么几个：

site_name：站点名称
site_url：站点 URL 链接
site_author：站点作者
site_description：站点描述
copyright：版权信息
repo_url：站点仓库 URL

其中，只有两个必须要填写的配置项就是 site_name 站点名称和 site_url 站点 URL 链接。例如：

1
2
3
site_name: "My Notes"

site_url: "http://<domain>:<port>/<project>"

但如果我们使用的是，mkdocs serve 来本地运行，那么无需填写 site_url，因为 MkDocs 会自动将其挂在本地的 http://127.0.0.1:8000/<your-site-project>。

除此之外的选项都是选填，如果填写了则 MkDocs 会将其作为元数据或元素渲染最后的 HTML 中。

添加文档路径

既然我们想要搭建的是一个文档站点，那么文档内容才是关键，除了对内容进行必要的排版校对之外，如何组织文档或是让文档以清晰有层次的结构展示也是必不可少的。

MkDocs 提供了让使用者能够自由安排文档层级结构或目录编排的设置，这将决定最后文档在站点中的编排效果如何。这里主要是通过 nav 项来进行配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
nav:

  - "index.md"

  - user-guide:

      - quickstart: "user-guide/quickstart.md"

      - usage: "user-guide/how-to-use-MkDocs.md"

  - "about.md"

  - "license.md"

在该设置项中，使用了 YAML 所支持的列表语法，这和 Markdown 的无序列表语法是完全一致。默认情况下如果不指定键名，MkDocs 会自动根据列举的 Markdown 文件名字符串来确定最终该页面的名称如何；如果我们手动指定了键名，那么会优先以我们的键名为主，比如这里的 user-guide/usage 这一部分。

需要注意的是，前面对于 MkDocs 的快速介绍中我就有提到，MkDocs 默认会将项目目录下的 docs 目录作为默认的根路径，所以在 nav 设置中我们如果指定的是该目录下的其他内容，那么就是只需要填写相对路径。

这也是为什么在上述例子中的 user-guide 这一部分下的文档路径都不需要写成 docs/user-guide/XXXX.md 的原因。

同时，最终 MkDocs 也会根据 nav 配置的层级关系将内容的层级关系或包含关系一同渲染。

当然，如果你不想使用 MkDocs 的默认目录，那么你也可以通过修改 docs_dir 选项来指定对应的文件夹名称。但通常情况我们都不需要进行修改就已经能满足我们的基本需要了。

用扩展和主题武装 MkDocs

基本上我们只需要将站点信息和文档路径在 mkdocs.yml 文件中填写好就已经可以运行 MkDocs 了。不过 MkDocs 为使用者预留了可扩展的配置，方便使用者去添加其他开发者所开发的主题、扩展等功能。

Markdown 扩展

MkDocs 使用 Python-Markdown 库（Markdown 规范的 Python 实现）来渲染 Markdown 内容，因此 MkDocs 中对于 Markdown 内容渲染的扩展也是来自于此。我们可以在 Python-Markdown 的官方文档中浏览到目前所支持的 Markdown 扩展有哪些。

比如我在当中开启对于 Markdown 内容标题的固定标识符、脚注以及表格：

1
2
3
4
5
6
7
8
9
markdown_extensions:

  - toc:

      permalink: True

  - footnotes

  - tables

除此之外，Python-Markdown 还支持一些来自于第三方的 Markdown 扩展，你能在 Python-Markdown 的 Github 仓库中的 Wiki 页面找到符合你需要的扩展，比如支持数学公式、emoji 表情、增强 Markdown 语法等。

但这些第三方扩展都还是需要通过 pip工具（安装 Python 解释器时会自带）来进行安装，安装之后在 mkdocs.yml中的markdown_extension部分继续追加。

这里我下载了一个名为 markdown-checklist的扩展，使我的 Markdown 文档内容支持清单列表的预览样式。

1
pip install markdown-checklist

安装完成后将其添加到 markdown_extension 中，注意，这里是需要安装插件对应文档的名称来填写包含相应的 makeExtension 属性的模块或继承了 Markdown 库中 Extension 的类，所以我就填入了 markdown_checklist.extension 这一模块：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
markdown_extensions:

  - toc:

      permalink: True

  - footnotes

  - tables

  - markdown_checklist.extension

最后运行 MkDocs 后就可以看到其对应的效果了。