GitHub Pages 文档自动化部署 - MkDocs

这篇文章讲述了如何使用 GitHub Actions / Pages 自动化部署文档，以及遇到的坑。

如你所见，这个博客也是使用 GitHub Actions 自动部署在 GitHub Pages 上的。

这篇文章将以 MkDocs 为例讲述。

本地部署测试¶

首先你自己搭建的文档得在本地能用嘛，首先测试下本地是否能用：

mkdocs serve

mkdocs serve -a localhost:8001
mkdocs serve --dev-addr localhost:8001

创建本地 VCS 并和 GitHub 关联¶

这里以 PyCharm 为例：

创建本地 VCS¶

graph LR
  A[VCS] --> B;
  B[启用版本控制集成] --> C;
  C[选择 Git] --> D[确定];

然后选择提交。

和 GitHub 关联¶

这一步其实是在 GitHub 上自动创建一个同名仓库。如果仓库已经存在的话，可能需要 Merge 或者 Rebase。

graph LR
  A[Git] --> B;
  B[GitHub] --> C;
  C[在 GitHub 上共享项目] --> D[确定];

在 GitHub 上创建 Actions 任务¶

这一步坑巨多。

首先点击 Actions -> set up a workflow yourself

按照任何一个你能找到的 Pages 部署文档来写这个 yml 文件，这里我们采用 Material for MkDocs 的模板。

在 2022年4月6日 的时候我从这里找到的模板是这样的，随着时间的推移可能会有变更，建议从原文档去复制。

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

name: ci 
on:
  push:
    branches:
      - master 
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/[email protected]
      - uses: actions/[email protected]
        with:
          python-version: 3.x
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force

最终我的 main.yml（后来重命名成 ci.yml 了）长这样：

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

name: ci 
on:
  push:
    branches:
      - master 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/[email protected]
        with:  # mkdocs-blogging-plugin 给出的渲染问题解决方案
          fetch-depth: 0
      - uses: actions/[email protected]
        with:
          python-version: 3.x
      - run: pip install mkdocs
      - run: pip install mkdocs-material
      - run: pip install mkdocs-blogging-plugin  # 记得安装其他依赖的库
      - run: mkdocs gh-deploy --force

这个时候你就可以在 Actions 页面点 Start commit 了。只要你的本地部署可以通过，在 Actions 上应该也是可以通过的。

如果 Actions 的 build 或者 deploy 阶段出现了问题，说明可能是那几个 run 里出现了错误，那你应该在本地试一下：

• 是不是有包忘了 pip install ？
• 本地能正常 mkdocs build 嘛？

之前遇到了一个典型的问题导致 build 失败：

1
2
3

plugins:
  - blogging:
      locale: zh_CN

坑还没结束，继续往下看

设置 Pages¶

你以为这样就结束了？

还没有！

Actions 结束后会给你一个页面（当然也可以自己去找），你点开这个页面会直接告诉你 404。

这是因为你还没有为 Pages 指定具体的页面。

Actions 毕竟只是 Actions，他又不是和 Pages 联动的，所以你就算 Actions 编译出了网页也是不会给你自动部署到 Pages 上的。

接下来手动设置 Pages：

graph LR
  A[打开你的项目仓库] --> B;
  B[Settings] --> C;
  C[Pages] --> D[Source];

选择分支为 gh-pages，这是 Actions 自动构建的文件所存放的分支，目录选择 /。

点 save，这下是真没问题了。

（可选）使用自定义域名¶

使用自定义域名又会带来两个坑，无语。

首先你在设置 Source 的时候，能看到下面一栏是 Custom domain，这个就是设置自定义域名的地方，比如我这个博客构建在了 https://zhanbao2000.github.io/blog ，但是我想让 https://blog.arisa.moe/ 指向这个博客，就得修改这玩意。

直接在框框里写你的域名肯定是不行的，应该遵循以下步骤，以本站为例：

1. 找到你域名的 DNS 服务商，添加一个 CNAME 记录：

   blog.arisa.moe. 1   IN  CNAME   zhanbao2000.github.io.
   

2. 在刚刚那个框里输入 blog.arisa.moe，点 save。

过一会就好了。

你以为这样就完了？

先说解决方法再说原因。

解决方法是，在 docs 文件夹里创建一个 CNAME 文件，内容写上你的自定义域名，下次 Actions 运行的时候，Pages 就会自动把这个域名设置成自定义域名了。

参考以下：

• Deploying seems to overwrite custom domain #213
• gh-pages -d dist overwrites custom domain #127
• MkDocs - Custom Domains 👉 其实 MkDocs 官网有写

这些 issues 无一例外都提到了要创建一个 CNAME 文件来指示自己的自定义域名。但是距离 issue 提出好像已经过了5年了也没见到 GitHub 官方修复这个问题。

我自己推测的原因是这样的：

在 Pages 页面设置自定义域名的时候，实际上是在项目生成目录里自动创建了一个 CNAME 文件的，和我们手动创建的效果一样。但是在 Actions 运作的时候，会覆盖掉整个项目生成目录，包括这个 CNAME 文件。

那么就有两个办法来解决：

• 每次 Actions 结束之后，手动去 Pages 页面添加自定义域名。
• 让 Actions 结束之后，项目生成目录里始终有这个 CNAME 文件。

于是我们选择了后者。

评论