本文通过 语雀 编写，首发于 Olly’s Blog ，转载请注明出处。作者: Oliver

前言

「语雀」是一个「专业的云端知识库」，孵化自 蚂蚁金服 ，是 体验科技 理念下的一款创新产品，已是 10 万阿里员工进行文档编写、知识沉淀的标配。

语雀诞生伊始，只是希望能给工程师提供一个好用的工具用来写技术文档，达成「用 Markdown 写文档」这个小目标。但在产品研发的过程中，我们发现其实身边的每个人、每个团队、每个组织都有很多知识，但一直以来缺少一个好用的工具让这些知识不只是留在每个人的大脑或电脑里，还可以被记录、分享和交流。

所以，带着这颗初心，我们觉得语雀不应止步于服务工程师，应该致力于为每个想表达所思所想的人提供一款顺手的工具，让知识能得以记录和传播，让人们可以在「语雀」中平等快乐地创作和交流知识，让再小的个体也可以拥有自己的知识库。

准备 Hexo 博客

由于作者自从从 Typecho 阵营转入到 Hexo，一直在使用 Hexo 博客作为个人学习的博客，故食用本教程之前你需要搭建一个 Hexo 博客，具体可以前往我的个人博客搜索安装部署的方法。安装 yuque-hexo 插件后，需要在 package.json 中添加插件配置。官方配置如下：

package.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "name": "your hexo project",
  "yuqueConfig": {
    "postPath": "source/_posts/yuque",
    "cachePath": "yuque.json",
    "mdNameFormat": "title",
    "adapter": "hexo",
    "concurrency": 5,
    "baseUrl": "https://www.yuque.com/api/v2",
    "login": "user",
    "repo": "blog",
    "onlyPublished": true,
    "onlyPublic": false,
    "lastGeneratePath": "lastGeneratePath.log"
  }
}

但是作者配置里没有加上 token，token 记得自己修改一下，因此我们修改配置如下：

1
2
3
4
5
6
7
8
9
10
11
12
"yuqueConfig": {
  "postPath": "source/_posts/yuque",
  "cachePath": "yuque.json",
  "mdNameFormat": "title",
  "concurrency": 5,
  "baseUrl": "https://www.yuque.com/api/v2",
  "login": "oliver",
  "repo": "blog",
  "token": "*********************",
  "onlyPublished": true,
  "onlyPublic": false
},

推送 Hexo 目录

这里我们需要创建一个 GitHub 私有仓库用来存放 Hexo 源代码，这里可能有人发现主题目录无法推送，我们需要删除主题文件夹下的.git 文件夹，这样才能上传主题文件夹至私有仓库，然后运行git rm -r --cache .和git push -f。这种做法也有一个弊端就是主题不利于更新，所以我这里主题文件夹采用的是子模块的方式。

GitHub Action

通过 Action，github 可以循行 hexo 指令，比如将语雀文章同步到 source/_post/yuque，生成静态文件，上传 github pages 等等。

参考我的个人配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
# 当有改动推送到master分支时，启动Action
name: Hexo自动部署

on: [push, repository_dispatch]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: 检查分支
      uses: actions/checkout@v2
      with:
        ref: master #2020年10月后github新建仓库默认分支改为main，注意更改

    - name: 安装 Node
      uses: actions/setup-node@v1
      with:
        node-version: "12.x"

    - name: 安装 Hexo 及 yuque-hexo
      run: |
        export TZ='Asia/Shanghai'
        npm install hexo-cli -g
        npm install yuque-hexo -g
        yuque-hexo clean
        yuque-hexo sync

    - name: 配置Git用户名邮箱
      run: |
        git config --global user.name "Oliver"
        git config --global user.email "oliverxxx@gmail.com"

    - name: 更新 语雀拉取缓存及文章 #更新yuque 拉取的文章到GitHub仓库
      run: |
        # echo `date +"%Y-%m-%d %H:%M:%S"` begin > time.log
        git add .
        git commit -m "Refresh yuque `date +'%Y%m%d%H%M'`" -a

    - name: 推送 语雀拉取缓存及文章 #推送修改后的yuque json
      uses: ad-m/github-push-action@master
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}

    - name: 缓存 Hexo
      uses: actions/cache@v1
      id: cache
      with:
        path: node_modules
        key: ${{runner.OS}}-${{hashFiles('**/package-lock.json')}}

    - name: 安装依赖
      if: steps.cache.outputs.cache-hit != 'true'
      run: |
        npm install --save

    - name: 更新Butterfly主题
      run: |
        git submodule init
        git submodule update --remote

    - name: 生成静态文件
      run: |
        hexo clean
        hexo douban -bm
        hexo generate

    - name: 部署推送
      run: |
				hexo deploy

云函数

云函数是为了接收语雀的回调，也就是当我们更新删除新建知识库文章时，语雀就会向一个指定的 url 发起请求，云函数就用来接收这个请求。云函数接收到请求后，调用 github 的 api，运行 action，action 再执行 hexo 指令部署博客。这里是我使用的百度云函数内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# -*- coding: utf8 -*-
import requests

def main_handler(event, context):
    r = requests.post("https://api.github.com/repos/你的github用户名/源码仓库名/dispatches",
    json = {"event_type": "start"},
    headers = {"User-Agent":'curl/7.52.1',
              'Content-Type': 'application/json',
              'Accept': 'application/vnd.github.everest-preview+json',
              'Authorization': 'Token github的Token'})

    if r.status_code == 204:
        return "This's OK!"
    else:
        return r.status_code

Hexo 模板

为了更加方便的使用 Hexo Font-matter 插件的头部格式，我们只需要在语雀编辑器中，标题一下，正文以上的部位，添加如下内容,abbrlink 根据自己需求填写：

1
2
3
4
5
6
7
---
tags: [语雀, 教程, Hexo]
categories: [Course, Hexo]
updated: 2021-09-29 17:00:00
abbrlink: yuque-hexo
description: 本文章通过语雀编写~
---

另存为模板，每次写文章都应用此模板就可以了，每篇文章记得修改 abbrlink 地址。