GitHub Pages 文档自动化部署 - MkDocs
这篇文章讲述了如何使用 GitHub Actions / Pages 自动化部署文档,以及遇到的坑。
如你所见,这个博客也是使用 GitHub Actions 自动部署在 GitHub Pages 上的。
这篇文章将以 MkDocs 为例讲述。
本地部署测试¶
首先你自己搭建的文档得在本地能用嘛,首先测试下本地是否能用:
mkdocs serve
小提示
使用以下参数可以使 mkdocs 运行在指定地址和端口上:
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[确定];
注意有坑
记得在提交之前先创建好 .gitignore
文件,否则你提交之后还要继续提交一次 .gitignore
文件。
然后选择提交。
和 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 的模板。
小提示
用 MkDocs 官网 的也行,只不过人家不会告诉你怎么写这个 yml
文件。
在 2022年4月6日
的时候我从这里找到的模板是这样的,随着时间的推移可能会有变更,建议从原文档去复制。
main.yml(请勿直接使用) | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
注意有坑
首先他这个流程,很明显只用 pip
安装了 mkdocs-material
,但是它并没有安装 mkdocs
。其实这无所谓,因为 mkdocs-material
的 requirements.txt
中已经包含了 mkdocs
,会一并安装。
重点的地方是,如果你在本地构建的时候依赖了其他的库(比如 mkdocs-blogging-plugin
),那你得在 run:
中通过 pip install
安装这些库。
注意有坑
坑还没完,如果你和我一样是 mkdocs-blogging-plugin
的使用者,你还会遇到网站的渲染问题,这里官网也给了解决方案。
https://liang2kl.codes/mkdocs-blogging-plugin/#publish-with-github-pages
注意,请不要跟随官网那篇文档里所说的设定 locale: zh-CN
这个键,后面会说到原因。
最终我的 main.yml
(后来重命名成 ci.yml
了)长这样:
main.yml | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
这个时候你就可以在 Actions 页面点 Start commit
了。只要你的本地部署可以通过,在 Actions 上应该也是可以通过的。
如果 Actions 的 build
或者 deploy
阶段出现了问题,说明可能是那几个 run
里出现了错误,那你应该在本地试一下:
- 是不是有包忘了
pip install
? - 本地能正常
mkdocs build
嘛?
之前遇到了一个典型的问题导致 build 失败:
注意有坑
mkdocs-blogging-plugin
的官网 文档 里说,要在 blogging
里建一个 locale: zh-CN
来设置时间格式,但是实际这样做会报错:ValueError: expected only letters, got 'zh-cn'
,
解决方法:不要写 locale: zh-CN
,要写 locale: zh_CN
或者干脆写 locale: zh
mkdocs.yml | |
---|---|
1 2 3 |
|
坑还没结束,继续往下看
设置 Pages¶
你以为这样就结束了?
还没有!
Actions 结束后会给你一个页面(当然也可以自己去找),你点开这个页面会直接告诉你 404
。
这是因为你还没有为 Pages 指定具体的页面。
小提示
这里简单说一下,很多人认为 Actions
和 Pages
是一个东西,因为很多人经常用这俩一起来部署页面。但是其实这俩的功能是各有分工。
- Actions
的主要功能是编译,就是你指定一个环境,给出一些编译中要执行的命令行,然后给出你的源代码(这里的源代码 GitHub 会自动从你的 repo 里获取所以不用管),GitHub Actions 就会从源代码里编译出对应的静态文件,这些静态文件可能是各种文件,比如二进制文件,或者是网页。
- Pages
的主要功能是在 <user>.github.io
上部署网页。
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/ 指向这个博客,就得修改这玩意。
小提示
现在访问 https://zhanbao2000.github.io/blog 会被 301
重定向到 https://blog.arisa.moe/
直接在框框里写你的域名肯定是不行的,应该遵循以下步骤,以本站为例:
-
找到你域名的 DNS 服务商,添加一个 CNAME 记录:
blog.arisa.moe. 1 IN CNAME zhanbao2000.github.io.
-
在刚刚那个框里输入
blog.arisa.moe
,点save
。
过一会就好了。
你以为这样就完了?
注意有坑
如果你以为这样就完了,等你下次再通过 git push
提交文档/博客的时候,你就会发现你的自定义域名已经变成 404
了。
此时你打开 GitHub 对应仓库的 Settings 一看,好家伙,框框里什么都没有了。
先说解决方法再说原因。
解决方法是,在 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
文件。
于是我们选择了后者。
创建日期: 2022-04-06 16:25:14