使用 mirror 和 hugo 实现 github issue 的博客自动同步

[befovy]

一直觉得 Issue 是个特别好用的记录工具，看到很多人也直接把 Issue 作为个人博客。 Issue 可以碎片化的记录一些东西，然后在进行整理，最终形成一篇不错的博客内容。

Issue 适合记录博客，但我觉得直接以 Issue 的形式将内容展示给读者还是缺少了博客本来的样子。毕竟Issue不支持自定义主题。

我青睐的形式是：通过 Issue 进行写作，然后自动发布到博客站点。 所以就产生了 mirror 这个工具。

mirror 能够自动抓取 github 项目里的 issue，并输出为 hugo 支持的构建格式。 通过 hugo 自动生成静态网页，最终通过自动工具实现部署。

使用 github webhooks 以及很少的自动化脚本就可以实现这个过程的全自动化。

[befovy]

时隔大半年，github 私有项目都免费了，我的第一篇博客还没有写完。 真是要感叹一句，“时间都去哪了”.

[befovy]

mirror

mirror 通过 github 提供的 graphql 进行 Issues 内容抓取。
通过一些自定义规则，实现 Issues 内容的分类提取，并整理输出博客内容。

mirror 规则

mirror 配置文件

mirror 的配置文件使用 yaml 格式， 参考 conf.yaml
默认查找运行目录下的mirror.yaml 作为输入配置文件

配置文件中可定义多个内容来源。 每一种不同的内容来源，都有其具体的配置项。

内容来源 "issues" 具体的配置内容有

• token: github token, 需要有 issue 读取权限
• login: github username
• repo: 要抓取的 issue 所在的 repo 名称
• prefix: 输出文件名的统一前缀
• output: 转换成 hugo 博客内容后的本地输出目录，建议指定为 hugo 博客的 content 目录

内容来源 Issue 的抓取规则

1. draft

打开的Issue 视为博客草稿，不抓取。只抓取已经关闭的 Issue 内容。

2. content

issue 本身有 body 和 comment。 新建issue时的内容是body， 之后所有项目本人和其它 githuber 的追加的内容都是评论。

Mirror 支持将 Issue body 和 comment 都抓取下来余与body部分拼接合并作为完整博客内容。

由于 Issue 都是公开的，可能会被别人评论，作者还可能回复提问者。
为了区分这种情况，mirror 只拼接 comment 作者是项目作者本人， 且在 comment 开头有一句 html <!--mirror--> 注释语句的comment。

[befovy]

hugo

hugo 是一个非常棒的静态页面生成器，可以把 markdown 内容，搭配各种主题生成你想要的静态博客内容。 这些内容托管在 github pages 上博客就部署好了。

[befovy]

完整步骤

1. 生成项目
   在当前目录下创建 blog 目录，并在其中生成hugo 项目的基本配置

   hugo new site ./blog
   

2. 创建博客所需的github项目
   github 上存在一个特殊的仓库名，可以自动生成静态站点方文仓库中的 html 文件。
   这个仓库的具体命名规则是， <你的github账号>.github.io
   比如 befovy.github.io
   对应自动生成网站的网址就是这个仓库的名称，https://befovy.github.io

3. 在第二步的github 仓库中创建博客内容
   新建 issue ，记录你的想法，完成之后关闭 issue。
   如果想让一些issue 评论在最终生成的博客页面中也可见，在 issue 的评论开始输入 即可。

4. 使用 mirror 工具自动抓去 issues 内容到 hugo 项目中
   mirror 工具使用 go语言编写，目前没有提供直接可用的二进制包，需要从源码安装运行。
   配置好 go 环境后，安装mirror

   go get -u -v github.com/befovy/mirror
   cd $GOPATH/src/github.com/befovy/mirror
   

   按照 readme 中的说明设置所需配置文件，并运行程序

5. 安装 hugo 主题
   在hugo 主题中挑选一个自己喜欢的风格，安装到本地hugo项目中。
   这里安装 even 主题作为示例。
   安装主题后使用主题提供的默认hugo 项目配置

   git clone https://github.com/olOwOlo/hugo-theme-even themes/even
   cp themes/even/exampleSite/config.toml ./
   

6. 生成网站
   运行 hugo 命令生成静态内容，注意这里需要设置 baseUrl。

   hugo --theme=even --baseUrl="https://befovy.github.io/"
   

7. 提交至 github
   上一步命令中会在 public 文件夹下生成静态博客网站所需要的全部内容。
   将 public 目录中的内容全部提交到第二步创建的github仓库就大功告成了。
   👏

如果有兴趣和精力，还可以用 github 提供的 webhooks，自行配置服务器并利用 hooks 自动触发这些过程的执行，可实现博客的自动更新。