hexo+语雀自动构建-实现云端富文本写作

浏览:7385次阅读
没有评论

共计 8359 个字符,预计需要花费 21 分钟才能阅读完成。

本文章通过语雀编写
教程参考自 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+ 语雀自动构建 - 实现云端富文本写作

使用前的准备?

为了更好、更方便的完成 hexo× 语雀的部署。在开始流程搭建的操作前,你需要完成以下步骤。

账号的申请与授权

hexo+ 语雀自动构建 - 实现云端富文本写作

hexo+ 语雀自动构建 - 实现云端富文本写作

hexo+ 语雀自动构建 - 实现云端富文本写作

仓库的准备

如果你已经配置了 github action 你可以忽略这一步。
为了实现 hexo 的自动部署,需要将本地的源码文件交与 github 托管,你可以创建私有仓库(建议)也可以创建共有仓库。
首先在 github 上创建私有仓库。

hexo+ 语雀自动构建 - 实现云端富文本写作


步骤一:hexo 博客文章的迁移

仓库的创建

登陆 语雀,点击知识库 ? 新建知识库。将知识库的可见范围改为“互联网可见”。

hexo+ 语雀自动构建 - 实现云端富文本写作

文章的导入

点击知识库的管理按钮,选择新建下的导入,将博客中 _post 文章进行批量导入。

hexo+ 语雀自动构建 - 实现云端富文本写作

模板的创建

为了方便以后文档的撰写,可以新建模板。注意图片链接需要加上’’防止被渲染成链接。

hexo+ 语雀自动构建 - 实现云端富文本写作

如果你使用了 abbrlink,请手动填写 abbrlink。

---

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。

npm i -g yuque-hexo

修改 package.json

在第一个对象代码块后增加”yuqueConfig”代码块。

{
  "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”的字段。

hexo+ 语雀自动构建 - 实现云端富文本写作

  • token 是在右上角头像 -> 账户设置 -> Token 添加的,权限的话只给读取就可以。复制粘贴获取的”token”字段。

hexo+ 语雀自动构建 - 实现云端富文本写作

修改“scripts”增加”sync”:“yuque-hexo sync”和“clean:yuque”:“yuque-hexo clean”。

{
  "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 创建自己主题的方法,这里暂时不予以介绍。

* 修改 hexo 主题文件中的 meta

以 butterfly 主题为例,
打开主题文件的 /themes/butterfly/layout/includes/head.pug。
在 meta (name=”theme-color”content=themeColor) 后方添加 meta (name=”referrer”content=”no-referrer”)。
该步骤是确保语雀中的图片可以正常加载。

meta(name="theme-color" content=themeColor)
meta(name="referrer" content="no-referrer")

修改 hexo 的 _config,yml

前往博客的根目录,修改 hexo 的 _config,yml 中关于 develop 的配置。

deploy:
  type: git
  repository:
   github: https:// 用户名: 保存在 txt 中的密钥 @github.com/ 用户名 / 仓库名.git
  branch: master


这里只列出一种简单的方案,其他的有时间再介绍。

创建 github action 脚本

在博客根目录下新建.github 文件夹(点不要漏掉了),在该文件夹下新建 workflows 文件夹。

hexo+ 语雀自动构建 - 实现云端富文本写作

在 workflows 文件夹下新建 autodeploy.yml。并填入以下代码。
【更新 语雀拉取缓存及文章】【部署】 user.name 和 user.email 后面的“”信息修改为自己的信息,注意对齐。

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

上传博客源码

打开终端输入以下命令,上传你的博客源码到私有源码仓库。

git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/ 你的用户名 / 你的私有博客源码仓库名.git
git push -u origin master

进行云端调试

上传后你会发现 github action 生效。等待几分钟后,如果打勾,就说明部署成功。如果未打勾请检查出错的步骤。

hexo+ 语雀自动构建 - 实现云端富文本写作


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。

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 路径作为触发链接,在语雀中进行配置。

百度云方案(推荐)

新建一个云函数

登陆后,点击创建函数。

hexo+ 语雀自动构建 - 实现云端富文本写作

选择空白函数后,超时设置 10s,运行时选择 python2.7。点击下一步。
hexo+ 语雀自动构建 - 实现云端富文本写作

选择 HTTP 触发器,URL 路径填’/‘,HTTP 方法填写 POST 和 GET,然后点击提交。
hexo+ 语雀自动构建 - 实现云端富文本写作

点击函数,选择函数列表,将以下代码粘贴并保存,将用户名,仓库地址改为自己的信息。将保存的私钥进行替换 ****,token 字段需要保留。测试代码,当返回”This’s OK!”且 github action 开始运行则说明成功。
hexo+ 语雀自动构建 - 实现云端富文本写作

hexo+ 语雀自动构建 - 实现云端富文本写作

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 路径作为触发链接,在语雀中进行配置。
hexo+ 语雀自动构建 - 实现云端富文本写作

腾讯云方案(不推荐,有使用期限)

新建一个云函数

腾讯云方案目前有 1 年的使用期限,目前在尝试阿里云方案和 vercel 方案。

登陆后,点击新建按钮。

hexo+ 语雀自动构建 - 实现云端富文本写作

填写基本信息。选择运行环境为 python2.7, 以空白方式创建。

hexo+ 语雀自动构建 - 实现云端富文本写作

填写以下脚本。将用户名,仓库地址改为自己的信息。将保存的私钥进行替换 ****,token 字段需要保留。

hexo+ 语雀自动构建 - 实现云端富文本写作

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 开始运行则说明成功。

新建一个触发条件

点击触发管理,新建触发器。点击提交后复制访问路径。

hexo+ 语雀自动构建 - 实现云端富文本写作

hexo+ 语雀自动构建 - 实现云端富文本写作

hexo+ 语雀自动构建 - 实现云端富文本写作


步骤五:配置语雀的 webhook

设定触发规则

在知识库中选择设置。

hexo+ 语雀自动构建 - 实现云端富文本写作

设定触发规则。粘贴在云函数处获取的访问路径(腾讯云)或 URL 链接(百度云)。

hexo+ 语雀自动构建 - 实现云端富文本写作

设置完毕后,你可以尝试发布一篇文章进行测试。如果 github action 执行则说明配置成功。
具体的样式测试请参考 CC 的部落格


本文转载: https://zfe.space/post/554e.html

正文完
 0
(未见秋)
版权声明:本站原创文章,由 (未见秋) 于2021-12-15发表,共计8359字。
转载说明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。
评论(没有评论)