在线文档生成工具 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 :
安装步骤
$ 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