本文章通过语雀编写
教程参考自 https://www.zhwei.cn/hexo-github-actions-yuque/
作者：hongwei
什么是语雀？
「语雀」是一个「专业的云端知识库」，孵化自 蚂蚁金服 ，是 体验科技 理念下的一款创新产品，已是 10 万阿里员工进行文档编写、知识沉淀的标配。
语雀诞生伊始，只是希望能给工程师提供一个好用的工具用来写技术文档，达成「用 Markdown 写文档」这个小目标。但在产品研发的过程中，我们发现其实身边的每个人、每个团队、每个组织都有很多知识，但一直以来缺少一个好用的工具让这些知识不只是留在每个人的大脑或电脑里，还可以被记录、分享和交流。
所以，带着这颗初心，我们觉得语雀不应止步于服务工程师，应该致力于为每个想表达所思所想的人提供一款顺手的工具，让知识能得以记录和传播，让人们可以在「语雀」中平等快乐地创作和交流知识，让再小的个体也可以拥有自己的知识库。
使用 hexo× 语雀的初衷？
在写教程之前先来几句废话。
笔者在使用 hexo 撰写博客时很不习惯使用 md 格式书写文档，同时 md 格式文档的排版需要进行 hexo s 才能进行预览。对于写作而言，大量的时间花费在样式调试和终端命令上，无法获取最纯粹的写作体验。
于是笔者就在思考如何能够像 wordpress 一样，优雅得实现博客的撰写，同时又完全摆脱进行终端上的操作，完全实现云上写作。就在这时，HEO 大佬 提醒我说，为什么不试试阿里爸爸的语雀呢。于是，抱着试一试的心态，我和CC 康纳百川同学 进行了语雀云写作的尝试。
通过本教程，你可以将你的文章储存在云端，实现云端写作（不限于 MAC 系统、Windows 系统、手机微信小程序），摆脱本地机器的限制。除此之外，优秀简约的富文本编辑器能极大提升你的写作效率，使你能更专注于文本的写作。通过结合 github action（github 自动部署）、serverless 云函数（腾讯云 API，用于部署事件的触发）、语雀（文档的发布）、Hexo（博客系统）自动实现文章发布到博客展现的流程。
使用前的准备？
为了更好、更方便的完成 hexo× 语雀的部署。在开始流程搭建的操作前，你需要完成以下步骤。
账号的申请与授权
仓库的准备
如果你已经配置了 github action 你可以忽略这一步。
为了实现 hexo 的自动部署，需要将本地的源码文件交与 github 托管，你可以创建私有仓库（建议）也可以创建共有仓库。
首先在 github 上创建私有仓库。
步骤一：hexo 博客文章的迁移
仓库的创建
登陆语雀，点击知识库 👉 新建知识库。将知识库的可见范围改为“互联网可见”。
文章的导入
点击知识库的管理按钮，选择新建下的导入，将博客中_post 文章进行批量导入。
模板的创建
为了方便以后文档的撰写，可以新建模板。注意图片链接需要加上’’防止被渲染成链接。
如果你使用了 abbrlink，请手动填写 abbrlink。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| ---
title: 教程：hexo×语雀 实现云端富文本写作
author: Zhu Fue
tags:
• 教程
• Butterfly主题
• DIY
categories:
• 教程
cover: 'zfe.space/images/letter/y.png'
top_img: 'zfe.space/images/letter/y.png'
abbrlink: 554e
date: 2020-12-16 11:42:00
---
|
步骤二：安装语雀插件进行本地调试
为了确保在云端能够正常生成博客，需要首先在本地进行调试。
语雀插件的安装
首先在根目录打开终端安装 yuque-hexo。
修改 package.json
在第一个对象代码块后增加”yuqueConfig”代码块。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
| {
"name": "hexo-site",
"version": "0.0.0",
"private": true,
"scripts": {
"build": "hexo generate",
"clean": "hexo clean",
"deploy": "hexo deploy",
"server": "hexo server"
},
"yuqueConfig": {
"postPath": "source/_posts",
"cachePath": "yuque.json",
"mdNameFormat": "slug",
"adapter": "markdown",
"concurrency": 5,
"baseUrl": "https://www.yuque.com/api/v2",
"login": "bingkanuo",
"repo": "sffipz",
"token": "***********************",
"onlyPublished": true,
"onlyPublic": true
},
|
其中需要修改”login”、”repo”、”token”字段。
- 点击进入博客的知识库，在浏览器地址栏中将用户名和仓库名复制分别粘贴为”login”、”repo”的字段。
- token 是在右上角头像 -> 账户设置 -> Token 添加的，权限的话只给读取就可以。复制粘贴获取的”token”字段。
修改 “scripts”增加”sync”: “yuque-hexo sync”和 “clean:yuque”: “yuque-hexo clean”。
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
71
72
73
74
| {
"name": "hexo-site",
"version": "0.0.0",
"private": true,
"scripts": {
"build": "hexo generate",
"clean": "hexo clean",
"deploy": "hexo deploy",
"server": "hexo server",
"sync": "yuque-hexo sync",
"clean:yuque": "yuque-hexo clean"
},
"yuqueConfig": {
"postPath": "source/_posts",
"cachePath": "yuque.json",
"mdNameFormat": "slug",
"adapter": "markdown",
"concurrency": 5,
"baseUrl": "https://www.yuque.com/api/v2",
"login": "bingkanuo",
"repo": "sffipz",
"token": "***********************",
"onlyPublished": true,
"onlyPublic": true
},
"hexo": {
"version": "5.2.0"
},
"dependencies": {
"yuque-hexo": "^1.6.0",
"gulp": "^4.0.2",
"gulp-base64": "^0.1.3",
"gulp-htmlmin": "^5.0.1",
"gulp-tobase64": "^1.1.2",
"hexo": "^5.0.0",
"hexo-abbrlink": "^2.2.1",
"hexo-deployer-git": "^2.1.0",
"hexo-generator-archive": "^1.0.0",
"hexo-generator-baidu-sitemap": "^0.1.9",
"hexo-generator-category": "^1.0.0",
"hexo-generator-feed": "^3.0.0",
"hexo-generator-index-pin-top": "^0.2.2",
"hexo-generator-sitemap": "^2.1.0",
"hexo-generator-tag": "^1.0.0",
"hexo-helper-live2d": "^3.1.1",
"hexo-offline-popup": "^1.0.3",
"hexo-renderer-ejs": "^1.0.0",
"hexo-renderer-marked": "^3.0.0",
"hexo-renderer-pug": "^1.0.0",
"hexo-renderer-stylus": "^1.1.0",
"hexo-server": "^1.0.0",
"hexo-tag-aplayer": "^3.0.4",
"hexo-wordcount": "^6.0.1",
"live2d-widget-model-unitychan": "^1.0.5",
"workbox-build": "^5.1.4"
},
"devDependencies": {
"@babel/core": "^7.12.3",
"@babel/preset-env": "^7.12.1",
"del": "^6.0.0",
"gulp": "^4.0.2",
"gulp-babel": "^8.0.0",
"gulp-clean-css": "^4.3.0",
"gulp-cli": "^2.3.0",
"gulp-html-css-js-base64": "^0.0.4",
"gulp-htmlclean": "^2.7.22",
"gulp-htmlmin": "^5.0.1",
"gulp-imagemin": "^7.1.0",
"gulp-imgs-base64": "^1.0.2",
"gulp-minify-inline-json": "^1.3.4",
"gulp-uglify": "^3.0.2",
"gulp-uglify-es": "^2.0.0"
}
}
|
进行本地调试
添加完成后保存，在执行命令前，请先备份自己的_post 文件夹，因为语雀的下载操作会覆盖原有的_post 文件夹。
在终端中输入‘yuque-hexo sync’就会把语雀的文章给下载下来。
然后通过‘hexo g&hexo s’进行调试。
ps：输入‘yuque-hexo clean’就会清除_post 下的所有文章。
如果存在外挂标签，请确保外挂标签格式的书写规范，否则容易报错。
步骤三：配置 github action
删除主题版本的控制文件
因为在仓库里面再放一个仓库是没法把里面那个仓库 push 到 github 的，只会传一个空文件夹，会导致后期博客成了空白页面，需要把 git clone 的 hexo 主题里的.git 文件夹给删掉。
这里只列出了最简单的方法，另外你也可以尝 fork 创建自己主题的方法，这里暂时不予以介绍。
以 butterfly 主题为例，
打开主题文件的/themes/butterfly/layout/includes/head.pug。
在 meta(name=”theme-color” content=themeColor)后方添加 meta(name=”referrer” content=”no-referrer”)。
该步骤是确保语雀中的图片可以正常加载。
1
2
| meta(name="theme-color" content=themeColor)
meta(name="referrer" content="no-referrer")
|
修改 hexo 的_config,yml
前往博客的根目录，修改 hexo 的_config,yml 中关于 develop 的配置。
1
2
3
4
5
6
7
8
9
|
deploy:
type: git
repository:
github: https://用户名:保存在txt中的密钥@github.com/用户名/仓库名.git
branch: master
|
这里只列出一种简单的方案，其他的有时间再介绍。
创建 github action 脚本
在博客根目录下新建.github 文件夹（点不要漏掉了），在该文件夹下新建 workflows 文件夹。
在 workflows 文件夹下新建 autodeploy.yml。并填入以下代码。
将【更新 语雀拉取缓存及文章】与【部署】 user.name 和 user.email 后面的“”信息修改为自己的信息，注意对齐。
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
| name: 自动部署
on: [push, repository_dispatch]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: 检查分支
uses: actions/checkout@v2
with:
ref: master
- name: 安装 Node
uses: actions/setup-node@v1
with:
node-version: "12.x"
- name: 安装 Hexo
run: |
export TZ='Asia/Shanghai'
npm install hexo-cli -g
npm install yuque-hexo -g
yuque-hexo clean
yuque-hexo sync
- name: 更新 语雀拉取缓存及文章
run: |
echo `date +"%Y-%m-%d %H:%M:%S"` begin > time.log
git config --global user.email "499984532@qq.com"
git config --global user.name "Zfour"
git add .
git commit -m "Refresh yuque json" -a
- name: 推送 语雀拉取缓存及文章
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: 生成静态文件
run: |
hexo clean
hexo g
- name: 部署
run: |
git config --global user.name "Zfour"
git config --global user.email "499984532@qq.com"
hexo deploy
|
上传博客源码
打开终端输入以下命令，上传你的博客源码到私有源码仓库。
1
2
3
4
5
| git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/你的用户名/你的私有博客源码仓库名.git
git push -u origin master
|
进行云端调试
上传后你会发现 github action 生效。等待几分钟后，如果打勾，就说明部署成功。如果未打勾请检查出错的步骤。
time.log 文件最近似乎不会自动生成，所有如果 action 不成功，请手动在仓库里新建 time.log
步骤四：配置云函数
vercel 方案（推荐）
为了方便大家调用，我用 python 写了一个 api。
比较蛋疼的是，在仓库里填写 github 的私钥 github 会自动删除私钥。所以我试了好久都没成功。
因此，我直接将 api 设置成了参数传递型的，供大家调用。
api 地址：https://yuque-vercel-webhook-api.vercel.app/api?。
当然你也可以fork 项目在 vercel 中自行搭建，将‘https://yuque-vercel-webhook-api.vercel.app’更换为你的 app 应用链接。
你需要传递的参数有 token，user，source。
1
2
3
4
5
6
7
8
| https://yuque-vercel-webhook-api.vercel.app/api?
token='{填写你的github私钥}'&
user='{填写你的github用户名}'&
source='{填写你的github仓库地址}'
示例：
https://yuque-vercel-webhook-api.vercel.app/api?token='8888888888'&user='Zfour'&source='my-blog-source-file'
将这个URL路径作为触发链接，在语雀中进行配置。
|
修改触发链接里的参数项，访问这个链接，如果出现‘This’s OK!’说明配置成功。
复制 URL 路径作为触发链接，在语雀中进行配置。
百度云方案（推荐）
新建一个云函数
登陆后，点击创建函数。
选择空白函数后，超时设置 10s，运行时选择 python2.7。点击下一步。
选择 HTTP 触发器，URL 路径填’/‘，HTTP 方法填写 POST 和 GET，然后点击提交。
点击函数，选择函数列表，将以下代码粘贴并保存，将用户名，仓库地址改为自己的信息。将保存的私钥进行替换****，token 字段需要保留。测试代码，当返回”This’s OK!” 且 github action 开始运行则说明成功。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
import requests
def handler(event, context):
r = requests.post("https://api.github.com/repos/Zfour/my-blog-source-file/dispatches",
json = {"event_type": "run-it"},
headers = {"User-Agent":'curl/7.52.1',
'Content-Type': 'application/json',
'Accept': 'application/vnd.github.everest-preview+json',
'Authorization': 'token *******************'})
if r.status_code == 204:
return "This's OK!"
else:
return r.status_code
|
复制 URL 路径作为触发链接，在语雀中进行配置。
腾讯云方案（不推荐，有使用期限）
新建一个云函数
腾讯云方案目前有 1 年的使用期限，目前在尝试阿里云方案和 vercel 方案。
登陆后，点击新建按钮。
填写基本信息。选择运行环境为 python2.7,以空白方式创建。
填写以下脚本。将用户名，仓库地址改为自己的信息。将保存的私钥进行替换****，token 字段需要保留。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
import requests
def main_handler(event, context):
r = requests.post("https://api.github.com/repos/Zfour/my-blog-source-file/dispatches",
json = {"event_type": "run-it"},
headers = {"User-Agent":'curl/7.52.1',
'Content-Type': 'application/json',
'Accept': 'application/vnd.github.everest-preview+json',
'Authorization': 'token *******************'})
if r.status_code == 204:
return "This's OK!"
else:
return r.status_code
|
点击保存并测试，如果返回”This’s OK!” 且 github action 开始运行则说明成功。
新建一个触发条件
点击触发管理，新建触发器。点击提交后复制访问路径。
步骤五：配置语雀的 webhook
设定触发规则
在知识库中选择设置。
设定触发规则。粘贴在云函数处获取的访问路径（腾讯云）或 URL 链接（百度云）。
设置完毕后，你可以尝试发布一篇文章进行测试。如果 github action 执行则说明配置成功。
具体的样式测试请参考CC 的部落格
总结
如果你实在不知道该怎么配置。
小冰也提供代配置部署服务，服务费 10 元。
配置 gulp 的话 12 元。
需提供你的手机号，github 账号密码及博客源码。
请和我 qq 私聊。
其他问题请在评论区留言。
