通过 Github Actions 部署 Mkdocs 文档

微生自怡
2023-12-01

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: 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文件,内容如下:

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。未来的提交也会出发这个流程。

 类似资料: