Mkdocs 是一个采用 Python 构建轻量级的静态 HTML 在线文档框架，内置部署到 Github Pages 的功能。我用来创建实践指南，用来做个人的知识积累。

安装 Mkdocs 以及 Mkdocs 主题

Mkdocs 以及主题都通过pip安装，例如我采用的mkdocs-material主题，如下所示：

pip install --user mkdocs mkdocs-material

值得一说的是，如果你安装主题，mkdocs 会作为依赖被安装。

更多的主题请参考 Wiki 页：https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes

创建并测试站点

通过mkdocs new <目录>就可以快速创建文档站点。目录里会生成mkdocs.yml文件和docs目录，目录内有默认的index.md文件，你可以修改和增加文件。

在所在目录执行mkserve，你就可以在http://localhost:8000看到初始化的文档。Mkdocs 会监测目录的改动并重新生成站点更新浏览器。

但如果你修改了配置，比如主题。就有可能出错中断进程。

这时站点还没有加载主题，你要修改mkdocs.yml，增加theme配置：

theme: name: materiallanguage: zhhighlightjs: true

不同的主题有不同的参数配置，详情可以参考对应主题的文档。

HTML 生成和部署

执行mkdocs build会新建site目录，并将 markdown 文件构建为 html 文件。

执行mkdocs gh-deploy就可以site中的 html 内容提交到代码仓库的gh-pages分支上，你要在 Github 上 代码库的配置中起用 Pages 才可以看见站点，地址是 https://<你的用户名>.github.io/<你的代码仓库> 。

通过 Github Actions 部署到 Github Pages

我们可以用 Github Actions 把上述的构建和发布工作自动化，只需要在代码库上新建.github/workflow/gh-deploy.yml文件，内容如下：

name: Deploy to Github Pageson:push:branches:- master- mainjobs:deploy:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v2- uses: actions/setup-python@v2with:python-version: 3.x- uses: actions/cache@v2with:key: ${{ github.ref }}path: .cache- run: pip install mkdocs-material- run: mkdocs gh-deploy --force

提交后，你就可以看到自己的站点自动部署到 Github Pages。未来的提交也会出发这个流程。