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

安装 Mkdocs 以及 Mkdocs 主题 #

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

1

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配置：

1
2
3
4

theme: 
  name: material
  language: zh
  highlightjs: 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文件，内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

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

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