|    

如何使用github pages和github actions构建静态个人博客站点

update at 2021

更新：github开放action功能后,travis-ci已经没有必要了,目前博客使用zhimoe仓库管理源码,使用action编译后将public目录同步到zhimoe.github.io仓库的gh-pages分支.
注意,由于使用了jsdelivr的cdn功能,切换分支后theme的相关静态文件的path也要修改.

github给个人和组织免费提供github pages功能. 就是说如果有个repo的名字为 zhimoe.github.io (zhimoe 为你的github username), 那么这个repo里面的master或者gh-pages分支的内容如果存在index.html, 那么其他人可以通过 https://zhimoe.github.io 访问这个站点.

借助于一些static gen工具,你可以将你的markdown转换为一个静态网站(html,js,css). 然后把静态网站的内容上传到刚说的repo中, 就有一个自己的博客站点了. static gen工具非常多, github推荐的是Jekyll(ruby), 主流的还有hexo(js)和hugo(go), hexo因为是基于js的,所以高质量的主题多(因为做主题是需要js,css技能), hugo的编译快些, 但是好看的主题不多. 高质量的主题除了美观可能还需要考虑移动端(responsive),评论, 访问统计等各种功能. 每个gen工具都有自己的主题站点. hugo的主题在这里找: hugo themes.

制作github pages站点的一般做法是把代码(放图片和markdown)放在master分支,static gen编译后的(html,js,css,image)内容放在gh-pages分支.然后在settings里面设置. 这样就可以得到一个站点了. 这么做有个缺点,就是markdown文件会被别人整个下载过去,之前就遇到过一次. 正好github现在有3个免费私有仓库. 所以我把源码放在私有仓库zhimoe.github.io.src里面,而编译后的内容发布的 https://zhimoe.github.io上面去.

自动编译发布这个过程就是持续集成(continue integration,CI)了, 即我提交一个markdown文件,我的主页会自动看到这篇文章, 不需要我在本地编译再提交编译结果文件.travis-ci 提供了免费的github CI服务. 使用github账号登录就会有提示操作. 这里勾选私有仓库zhimoe.github.io.src, 然后在项目里面添加.travis.yml文件告诉travis如何编译和发布内容到个人站点.

markdown渲染设置

hugo使用BlackFriday渲染markdown文件,默认的设置有几个过于严格:

  • 没有硬换行,需要使用\来表示换行
  • 标题和#之间必须有空格
  • 代码块前面必须有空行

在config.toml可以修改这些配置:

# markdown解析引擎blackfriday配置, 
# extensions :  noEmptyLineBeforeBlock-代码块前面无需空行,hardLineBreak-换行无需使用backslash
# extensionsmask spaceHeaders-标题之间无需空格
[blackfriday]
  angledQuotes = true
  extensions = ["hardLineBreak","noEmptyLineBeforeBlock"]
  extensionsmask = ["spaceHeaders"]
  fractions = false
  plainIDAnchors = true

travis-ci配置

就是从一个私有的源码仓库编译,然后将编译后的文件强制覆盖到个人主页(即username.github.io这个仓库)的仓库中.具体的配置就不说了,注意是需要一个github的personal-access-key. 下面是.travis.yml内容:

dist: xenial
language: python
python: 3.7

# Handle git submodules yourself
git:
    submodules: false
# Use sed to replace the SSH URL with the public URL, then initialize submodules
before_install:
  - sudo apt update -qq
  - sudo apt -yq install apt-transport-https
  - echo -e "Host github.com\n\tStrictHostKeyChecking no\n" >> ~/.ssh/config
  - git config --global user.email ${GITHUB_EMAIL}
  - git config --global user.name ${GITHUB_USERNAME}
  - sed -i 's/[email protected]:/https:\/\/github.com\//' .gitmodules
  - git submodule update --init --recursive

install:
  # install latest hugo release version
  # - wget -qO- https://api.github.com/repos/gohugoio/hugo/releases/latest | sed -r -n '/browser_download_url/{/Linux-64bit.deb/{s@[^:]*:[[:space:]]*"([^"]*)".*@\1@g;p;q}}' | xargs wget
  # use local hugo pkg for speed
  - sudo dpkg -i hugo*.deb
  - rm -rf public 2> /dev/null

  # compile src to dist
script:
  - hugo -d ./dist/

after_success:
  - git clone https://zhimoe:${GITHUB_TOKEN}@github.com/zhimoe/zhimoe.github.io.git
  - cd zhimoe.github.io 
  - git rm -rf . && git clean -fxd 
  - mv -v ../dist/* .
  - git add .
  - git commit -m "update site"
  - git remote set-url origin https://zhimoe:${GITHUB_TOKEN}@github.com/zhimoe/zhimoe.github.io.git
  - git remote -v
  - git push -q -f

要点:

  • 在项目的源码中放了hugo的deb安装包,省去下载的过程
  • 主题以submodules放在themes目录中,所以编译前一定要git submodule update --init --recursive更新主题到本地.
  • 目标repo的远程仓库一定要在push前重新设置:git remote set-url origin xxx
0%