使用语雀 Webhooks 和 Netlify Functions 自动同步生成 Github Profile README

最近 Github 上了个骚功能。允许用户使用用户名同名仓库的 README.md 文件作为自己的简介页面。这个功能已经被玩出花来了。比如这位同学把做了一个自动更新的 README.md 拿来放博客和 Timeline。

那么问题来了，能不能把语雀知识库放到 README.md 上。

那当然可以。。

准备工作：

创建 Github 帐号同名 Repo

创建一个跟你的帐号一样的 Repo 就可以了。先什么都不用做

从语雀获取 token

右上角菜单，账户设置 -> Token，新建一个 token，赋予知识库和文档的读权限。 https://www.yuque.com/settings/tokens

创建完成之后把这个 token 拷贝下来。在 Github 上仓库的设置 -> Secrets 中新建一个 Secrets，命名为 YUQUE_TOKEN ，把语雀的 token 填进来。

配置 Github Action:

然后在仓库的 Actions 下创建一个新的 workflow

使用 actions/yuque-to-readme 生成 README.md

在右边的 Marketplace 里搜 yuque，找到 yuque to readme 的 action。

点进去。点右边的复制按钮，在左边的 action 编辑器，在 - uses: actions/checkout@v2 后粘贴。

粘贴之后提示要配置这些选项：

yuque-token:

因为刚刚配置了 Github 的 Secrets，所以这里写 ${{secrets.YUQUE_TOKEN}} 即可。

yuque-namespace:

这里填你需要拿来展示的知识库 namespace。比如要展示这个的目录，就写 yuque/blog

yuque-doc-public-only:

是否仅展示已发布的文章。默认为 true，这项可以删掉不填。

yuque-template-file:

readme 模板。因为 action 最后会覆盖掉 README.md，所以必须指定一个模板 README 文件用于生成最终的 README.md。不填也没关系，会使用默认的模板。

yuque-output-file:

输出文件。默认是 README.md

配置自动提交到 master

改完了还不够，必须自动提交到 master 才能生效。这里直接拷过去就可以了：

    - name: Commit and push if changed
      run: |-
        git add .
        git diff
        git config --global user.email "github-action-bot@example.com"
        git config --global user.name "GitHub Action Bot"
        git commit -m "Updated README" -a || echo "No changes to commit"
        git push

完整配置文件

# This is a basic workflow to help you get started with Actions

name: CI

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
    - uses: actions/checkout@v2

    - name: yuque to readme
      uses: RaoHai/yuque2Readme@1.0.2
      with:
        # secrets.YUQUE_TOKEN. 语雀的 token，去 https://www.yuque.com/settings/tokens 里找。需要读取你的知识库和文档。
        yuque-token: ${{secrets.YUQUE_TOKEN}}
        # 填你自己的空间标识。比如语雀的博客是： `yuque/blog`
        yuque-namespace: luchen/buzhou
        # 是否只列出已发布的文章
        yuque-doc-public-only: true
        # Which file to write
        yuque-output-file: README.md

    - name: Result
      run: |-
        cat README.skylark.md

    - name: Commit and push if changed
      run: |-
        git add .
        git diff
        git config --global user.email "github-action-bot@example.com"
        git config --global user.name "GitHub Action Bot"
        git commit -m "Updated README" -a || echo "No changes to commit"
        git push

看看效果！

看起来很不错。

自定义 README.md 模板

acions/yuque-to-readme 支持自定义 README 模板。使用 handlebars 语法。可以自己写 README 文件，中间插入一段语雀的文章列表。

在 Repo 下创建一个 README.yuque.template.md 文件，自由发挥。中间的 handlebars 语法中的变量可以参考 https://www.yuque.com/yuque/developer/docserializer。

<h2>Hi, I'm Rao Hai! <img src="https://github.githubassets.com/images/mona-whisper.gif" height="24" /></h2>
<img align='right' src="https://media.giphy.com/media/836HiJc7pgzy8iNXCn/giphy.gif" width="230" />
<p><em>Front-end Engineer at <a href="https://www.alipay.com/">Alipay</a> . </em>

<h4> Latest Blog Posts: </h4>

{{#each record}}
  - [{{title}} ( {{short created_at "MM-dd"}} · {{math likes_count "*" 7}} 颗稻谷)](https://yuque.com/{{@root.namespace}}/{{slug}})
{{/each}}


<p align="right"><a href="https://www.yuque.com/luchen/buzhou">➡️ More blog posts</a></p>
<p align="right">
  Generated by
  <a href="https://www.yuque.com">语雀</a>,
  <a href="https://github.com/marketplace/actions/yuque-to-readme">yuque to readme</a>,
  And Github Actions.
</p>

改一下 action 的配置，增加 yuque-template-file，指向刚刚创建的 README.yuque.template.md。

提交后等一分钟刷新看下。是不是很棒。

语雀文档更新后自动更新 README

现在只做到了从语雀更新 README。下一步是要解决在语雀文章增加、编辑的时候自动更新 README 的问题。

这里有两种方案：

一种是配置 Actions 的定时调度。例如把 Actions 中的 schedule 配置为每小时自动运行一次。
另一种是使用语雀的 Webhooks 能力，在语雀文档更新时自动唤起 Github Workflow，完成 README 的更新。

使用第二种方案有个问题。Github 并没有原生提供一个「唤起 Workflow」的 Webhook API。所以我们需要借助服务端能力完成这个功能。这里选用 Netlify Functions，是一个基于 AWS Lambda 的 Serverless 服务。

整个功能的架构应该是这样的：

具体逻辑可以参看 https://github.com/RaoHai/RaoHai/blob/master/src/webhook.js ，很简单，不赘述了。