部署 teedoc 生成的网站到 github pages

因为 github 提供免费的 pages 服务, 我们只需要将html页面提交到gh-pages分支, 然后在项目设置里面开启pages服务即可.

同时, 我们也将页面构建和推送做了自动化, 每次向仓库提交代码/文档, 都会触发github action自动构建并推送到gh-pages页面, 十分简单方便可靠!

克隆模板仓库

这里使用 teedoc 官网的源码作为模板, 访问 https://github.com/teedoc/template 或者 https://github.com/teedoc/teedoc.github.io
点击 Use this template
github use template
然后填写新的仓库名称(如果你不准备自定义域名,则仓库名字最好是teedoc.github.ioteedoc替换成你的用户名或者组织名)和描述,基于这个仓库新建一个你自己的仓库,现在你获得了和 teedoc官网一模一样的仓库了

会发现有一个.github/workflows的目录,这个就是github action的配置文件,我们利用这个功能来实现: 当我们更新仓库的源文件时, github action自动根据这个配置文件的命令构建生成静态网页,然后推送到这个仓库的gh-pages分支

其中sync_code_to_gitee.ymlsync_pages_to_gitee.yml 是用来将代码同步到 gitee 的, 可以将他们删除, 需要时请自行研究

自动触发构建

仓库每提交一次修改,会自动触发构建,构建完成后gh-pages分支就会出现生成的html页面, 可以在Actions栏看到进度和日志

如果是绿色的勾, 就代表成功了,否则就是失败了,可以点进去看构建日志报了什么错,一般都是前面的值填错了

设置 pages 服务

然后在设置里面找到 pages 服务设置,打开即可,然后访问对应的域名,可以勾选 Enforce HTTPS来使能HTTPS(推荐) 比如这里是https://teedoc.github.io/

注意如果根路径不是/,而且没有自定义域名(自定义域名见后面的介绍),比如https://teedoc.github.io/my_site/, 则需要在site_config.json中配置"site_root_url":"/my_site/"

Pages 服务自定义域名

部署好后会有一个默认的域名,比如teedoc.github.io, 如果想使用自己的域名,比如teedoc.neucrack.com,即需要自定义域名。

site_config.json文件中设置了网站根目录映射的文件目录,比如这里是pages/index/zh目录:

        "pages": {
            "/": "pages/index/zh",
            "/en/": "pages/index/en"
        },

在这个目录新建一个文件,取名CNAME注意没有后缀,然后写入自定义的域名比如teedoc.neucrack.com保存文件,提交即可

你可能在设置里面看到了custom domain的设置,但是需要像这里说的设置CNAME文件才能保持一直生效,不然下次提交自定义域名就失效了

自动构建进阶配置

.github/workflows/publish.yml 文件中配置了构建的流程, 主要包含了构建文档, 和推送文档到gh-pages分支, 可以根据情况修改脚本.

推送文档到gh-pages分支用了, github-pages-deploy-action 这个 github actioin 插件, 更多进阶的用法请阅读这个插件的文档

一般用上面的方式就足够了, 甚至不用配置任何参数就可以使用, 另外, publish.yml 底部提供了不用插件的推送写法, 如果你需要, 可以复制到上面使用, 使用时可能需要用到以下知识点:

  • 生成 ssh 密钥

在本地生成一对key(windows下需要先安装相关软件,请自行安装(安装git就会有))

ssh-keygen -t rsa -f key.txt

得到了key.txtkey.key.pub两个文件

  • 设置密钥

到文档项目的设置里面设置ssh密钥, 添加一个ssh密钥, 拷贝 key.txt.pub 中的内容,注意是pub文件,即公钥,选中允许写入权限, 名字随便取

然后点击Secrets,设置秘密键值对, 需要设置的变量有:

  • ACCESS_KEY: 复制key.txt中的内容
  • GIT_EMAIL: 设置一个git提交邮箱,设置你的github邮箱即可
  • GIT_NAME: 设置一个git提交名字,设置你的github名字即可
  • REPO: 仓库地址, 设置为组织名/仓库名或者用户名/仓库名,比如teedoc/teedoc.github.io即可

当然, 这些变量也可以通过优化脚本直接从提交记录中获得(除了ACCESS_KEY), 有兴趣可以优化, 也欢迎提交 PR