在线文档生成工具 mkdocs 使用方法

简介

mkdocs 是一款在线文档生成工具，可以生成比较漂亮的在线文档。比如我个人的C++笔记就是用它生成的：https://demon90s.github.io/CppStudy/

其实 mkdocs 功能就是把一堆 markdown 文档生成成一些 html 的静态页面。

mkdocs 的官网是：

https://www.mkdocs.org/

安装

官网安装参考：
https://www.mkdocs.org/user-guide/installation/

我测试安装的环境是 VirtualBox 中的 CentOS7 。关于如何在 VirtualBox 中安装 CentOS7 可以参考我这篇 BLOG ：https://www.cnblogs.com/demon90s/p/6086350.html

安装步骤

$ yum install python36
$ wget ftp://lovemiemie.xyz/pub/install_package/ubuntu/get-pip.py
$ python3.6 get-pip.py
$ pip install mkdocs
$ mkdocs --version

PS: 如果之前已经有安装了更低版本的 python ，那么使用pip前，最好加上 python3.6 -m 。比如 python3.6 -m pip install mkdocs 。不然可能会因为版本问题报错。

创建一个 mkdocs 项目

$ mkdocs new my-project
$ cd my-project

启动服务

mkdocs serve -a 10.0.2.15:8001

PS: 10.0.2.15 是虚拟机的默认地址。

虚拟机做端口转发，关于端口转发也可以参考上面引用的博客。

打开浏览器即可访问 127.0.0.1:8001

创建静态页面

mkdocs build

如何发布到 github page

首先需要有一个 github 账号，然后创建一个 git 仓库，在这里初始化 mkdocs 目录，之后就可以使用命令 mkdocs gh-deploy 来创建一个 github page 的分支，完毕后，mkdocs会打印出网站地址，然后就可以在网页上访问了。

PS： 由于目前国内网站访问 github 很不稳定，所以其实有一个云主机，将其部署在云主机上面也不错。方法就是先创建静态页面，然后将它放到适当的网站文件目录。

material 主题

我比较推荐使用 material 主题，可以在它的官网查看更多关于它的资料 https://squidfunk.github.io/mkdocs-material

安装：

pip install mkdocs-material

更新：

pip install --upgrade mkdocs-material

查询当前版本：

pip show mkdocs-material

主题的相关设置参考：
https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/