yuque-hexo

A downloader for articles from yuque（语雀知识库同步工具）

Usage

Premise

建议使用 Node.js >= 12

事先拥有一个 hexo 项目，并在 package.json 中配置相关信息，可参考例子。

Config

配置 YUQUE_TOKEN

出于对知识库安全性的调整，使用第三方 API 访问知识库，需要传入环境变量 YUQUE_TOKEN，在语雀上点击个人头像 -> 设置 -> Token 即可获取。传入 YUQUE_TOKEN 到 yuque-hexo 的进程有两种方式：

设置全局的环境变量 YUQUE_TOKEN
命令执行时传入环境变量
- mac / linux: YUQUE_TOKEN=xxx yuque-hexo sync
- windows: set YUQUE_TOKEN=xxx && yuque-hexo sync

配置图床TOKEN(可选)

语雀的url存在防盗链的问题，直接部署可能导致图片无法加载。如果需要语雀URL上传到图床中并替换原链接，就需要配置上传密钥。

访问图床的密钥管理获取密钥，然后传入密钥到yuque-hexo

腾讯云API密钥管理
阿里云API密钥管理
七牛云API密钥管理
又拍云操作员管理
GitHub图床生成Github Token

又拍云的SECRET_ID=操作员账号，SECRET_KEY=操作员密码

Github图床的SECRET_ID=用户名，SECRET_KEY=Github Token。注意在生成token时，记得勾选上读写权限，即 write:packages和read:packages
在设置YUQUE_TOKEN的基础上配置SECRET_ID和SECRET_KEY
命令执行时传入环境变量
- mac / linux: YUQUE_TOKEN=xxx SECRET_ID=xxx SECRET_KEY=xxx yuque-hexo sync
- windows: set YUQUE_TOKEN=xxx SECRET_ID=xxx SECRET_KEY=xxx && yuque-hexo sync

配置知识库

package.json

{
  "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": "yinzhi",
    "repo": "blog",
    "onlyPublished": false,
    "onlyPublic": false,
    "lastGeneratePath": "lastGeneratePath.log",
    "imgCdn": {
      "enabled": false,
      "concurrency": 0,
      "imageBed": "qiniu",
      "host": "",
      "bucket": "",
      "region": "",
      "prefixKey": ""
    }
  }
}

参数名	含义	默认值
postPath	文档同步后生成的路径	source/_posts/yuque
cachePath	文档下载缓存文件	yuque.json
lastGeneratePath	上一次同步结束的时间戳的文件
mdNameFormat	文件名命名方式 (title / slug)	title
adapter	文档生成格式 (hexo/markdown)	hexo
concurrency	下载文章并发数	5
baseUrl	语雀 API 地址	-
login	语雀 login (group), 也称为个人路径	-
repo	语雀仓库短名称，也称为语雀知识库路径	-
onlyPublished	只展示已经发布的文章	false
onlyPublic	只展示公开文章	false
imgCdn	语雀图片转CDN配置

slug 是语雀的永久链接名，一般是几个随机字母。

imgCdn 语雀图片转图床配置说明

注意：开启后会将匹配到的所有的图片都上传到图床

参数名	含义	默认值
enabled	是否开启	false
concurrency	上传图片并发数, 0代表无限制，使用github图床时，并发问题严重，建议设置为1	0
imageBed	选择将图片上传的图床目前支持腾讯云(cos)、阿里云(oss)和七牛云(qiniu)，又拍云(upyun)，Github图床(github) 默认使用七牛云	'qiniu'
host	使用七牛云/又拍云图床时，需要指定CDN域名前缀
bucket	图床的bucket名称	-
region	图床的的region	-
prefixKey	文件前缀	-

host 说明

由于七牛云默认使用CND进行图片外链访问（默认提供30天的临时域名或者添加自定义CDN域名），所以需要指定访问的域名前缀例如：'host': http://image.1874.cool，域名后面不需要加斜杠

又拍云和七牛云有点类似，默认使用临时域名访问，但不同的是又拍云的临时域名暂时是由服务名.test.upcdn.net组成，默认为http访问

如果使用临时域名，host可不填。使用自定义域名，默认为http访问，如果需要指定协议为https，则需要填写完整的域名

例如 'host': upyun.1874.cool或 https://upyun.1874.cool

Github图床的默认域名是raw.githubusercontent.com，如果要使用jsdelivr进行加速，可以配置host为cdn.jsdelivr.net，

例如 'host': cdn.jsdelivr.net

bucket和region说明

获取腾讯云的bucket和region，示例：{ bucket: "blog", region: "ap-guangzhou" }

获取阿里云的bucket和region，示例：{ bucket: "blog", region: "oss-cn-shenzhen" }

获取七牛云的bucket(空间)和region(机房)，示例：{ bucket: "blog", region: "Zone_z2" }

七牛云机房取值: 华东(Zone_z0)华北(Zone_z1)华南(Zone_z2)

又拍云没有bucket和region的概念，只有服务名。所以这里的bucket=服务名，region暂时保留不需要填写

Github图床也没有bucket和region的概念。所以bucket=仓库名，region暂时保留不需要填写

prefixKey 说明

如果需要将图片上传到bucket的根目录，那么prefixKey不用配置。

如果想上传到指定目录blog/image下，则需要配置prefixKey为"prefixKey": "blog/image"。

目录名前后都不需要加斜杠

配置示例: yuque-hexo配置示例

Install

npm i -g yuque-hexo
# or
npm i --save-dev yuque-hexo

Sync

yuque-hexo sync

Clean

yuque-hexo clean

Npm Scripts

{
  "sync": "yuque-hexo sync",
  "clean:yuque": "yuque-hexo clean"
}

Debug

DEBUG=yuque-hexo.* yuque-hexo sync

Best practice

另外 x-cold 本人提供了一个触发 Travis CI 构建的 HTTP API 接口，详情请查看文档 (请勿恶意使用)

Notice

语雀同步过来的文章会生成两部分文件；
- yuque.json: 从语雀 API 拉取的数据
- source/_posts/yuque/*.md: 生成的 md 文件

支持配置 front-matter, 语雀编辑器编写示例如下:

语雀编辑器示例，可参考原文

tags: [hexo, node]
categories: [fe]
cover: https://cdn.nlark.com/yuque/0/2019/jpeg/155457/1546857679810-d82e3d46-e960-419c-a715-0a82c48a2fd6.jpeg#align=left&display=inline&height=225&name=image.jpeg&originHeight=225&originWidth=225&size=6267&width=225

---

some description

<!-- more -->

more detail

- 如果遇到上传到语雀的图片无法加载的问题，可以考虑开启imgCdn配置或者参考这个处理方式yuque-hexo插件语雀图片防盗链限制的解决方案或者参考这个处理方式 #41

Example

yuque to hexo: x-cold/blog
yuque to github repo: txd-team/monthly
yuque-hexo配置示例

Changelog

v1.9.5

修复腾讯云图床/Github图床上传问题
图片上传失败时，取消停止进程
新增图片上传时的并发数concurrency，使用Github图床时，并发问题严重，建议设置为1

v1.9.4

🔥 新增GitHub图床和又拍云图床

v1.9.2

修复上传图片到图床时可能由于用户代理缺失导致403问题

v1.9.1

修复不使用图床配置时报错的问题

v1.9.0

🔥 支持腾讯云/阿里云/七牛云图床链接替换语雀链接

v1.8.0

🔥 支持自定义的适配器 adapter，具体查看配置示例

v1.7.0

🔥 支持配置 lastGeneratePath，同步文章后会记录一个时间戳，下一次同步文档时不再清空全部文档，只同步修改时间大于这个时间戳的文档
🔥 支持语雀提示区块语法
🐸 修复 front-matter 中 “:” 等特殊字符会导致文章无法正常生成
🐸 由于 prettier 不再支持 Node 8，markdown 格式化仅在 node 版本 >= 10 生效
🐸 现在必须配置 YUQUE_TOKEN 工具才能正常工作

v1.6.5

🔥 支持过滤 public 文章
🔥 生成的 markdown 自动格式化
🔥 移除去除语雀的锚点

v1.6.4

🐸 修复多行
的问题

v1.6.3

🔥 支持嵌套的 categories 解析 #56
🐸 使用 filenamify 修复因为特殊字符的标题，生成非法的文件名导致的程序错误

v1.6.2

🔥 使用 slug 自定义 urlname

v1.6.1

🐸 修复 tags 格式化问题

v1.6.0

🐸 修复 descrption 导致的 front-matter 解析错误问题
🔥 支持私有仓库同步
🔥 使用语雀官方的 SDK，支持 YUQUE_TOKEN，可以解除 API 调用次数限制

v1.5.0

支持自定义 front-matter

v1.4.3

支持过滤未发布文章 onlyPublished

v1.4.2

支持纯 markdown 导出
支持请求并发数量参数 concurrency

v1.4.0

升级项目架构，增强扩展性，支持自定义 adpter

v1.3.1

修复 front-matter 处理格式问题

v1.2.1

修复 windows 环境下命令行报错的问题
支持自定义文件夹和博客文件命名

v1.1.1

支持 hexo-front-matter，可以在文章中编辑 tags / date 等属性

x-cold / yuque-hexo

readme

yuque-hexo

Usage

Premise

Config

配置 YUQUE_TOKEN

配置图床TOKEN(可选)

配置知识库

Install

Sync

Clean

Npm Scripts

Debug

Best practice

Notice

Example

Changelog

v1.9.5

v1.9.4

v1.9.2

v1.9.1

v1.9.0

v1.8.0

v1.7.0

v1.6.5

v1.6.4

v1.6.3

v1.6.2

v1.6.1

v1.6.0

v1.5.0

v1.4.3

v1.4.2

v1.4.0

v1.3.1

v1.2.1

v1.1.1

x-cold / yuque-hexo

readme

yuque-hexo

Usage

Premise

Config

配置 YUQUE_TOKEN

配置 图床TOKEN(可选)

配置知识库

Install

Sync

Clean

Npm Scripts

Debug

Best practice

Notice

Example

Changelog

v1.9.5

v1.9.4

v1.9.2

v1.9.1

v1.9.0

v1.8.0

v1.7.0

v1.6.5

v1.6.4

v1.6.3

v1.6.2

v1.6.1

v1.6.0

v1.5.0

v1.4.3

v1.4.2

v1.4.0

v1.3.1

v1.2.1

v1.1.1

配置图床TOKEN(可选)