语雀-Hexo

语雀 + Elog + Hexo + GitHub Actions + Vercel 博客解决方案

发表于 更新于

写作注意事项

前言

在使用 Elog 同步语雀上的文档时，因为是将富文本向下转成 markdown，会有很多样式损失。这是由于 markdown 样式集合＜ 语雀样式集合。所以在语雀上书写时，得按照 markdown 支持的样式进行写作。

可以在这里看到语雀文档被导出为 markdown 时的样式损失程度

如果你不能接受样式损失，可能 markdown 并不适合你，隔壁 NotionNext 可能更适合你搭建文档站点。

语雀格式注意点

不要使用 markdown 不支持的样式/语法

例如字体颜色、多级折叠块、分栏、数据表、嵌入等。导出为 markdown 都不能正常展示。

使用双换行符或结尾双空格进行段落换行

根据 markdown 的写作建议，可以使用双换行符或结尾双空格进行段落换行，而语雀导出的 markdown 不会使用此方式，所以会导致段落换行失败。这里就使用了结尾双空格换行
所以在语雀书写文档时，就需要使用此方法进行段落换行。

语雀一级标题留给文档标题（建议）

VitePress 的正文缺少文档标题可能会比较别扭，所以这里建议语雀一级标题留给文档标题，正文从二级标题开始写作

部分高亮块在 Hexo 可能不支持显示

可能需要 hexo 相关插件，待完善

发表于 更新于

Elog配置详解

参考 Elog 文档，本博客的 Elog 的配置如下：

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
module.exports = {
  write: {
    platform: 'yuque',
    // Token 模式（需要语雀超级会员）
    yuque: {
      token: process.env.YUQUE_TOKEN,
      login: process.env.YUQUE_LOGIN,
      repo: process.env.YUQUE_REPO,
      onlyPublic: false,
      onlyPublished: true,
    },
    // 账号密码模式
    "yuque-pwd": {
      username: process.env.YUQUE_USERNAME,
      password: process.env.YUQUE_PASSWORD,
      login: process.env.YUQUE_LOGIN,
      repo: process.env.YUQUE_REPO,
    }
  },
  deploy: {
    platform: 'local',
    local: {
      outputDir: './source/_posts',
      filename: 'title',
      format: 'markdown',
      catalog: false,
      frontMatter: {
        enable: true,
        include: ['categories', 'tags', 'title', 'date', 'updated', 'permalink', 'cover', 'description'],
        timeFormat: true,
      }
    }
  },
  image: {
    enable: true,
    platform: 'local',
    local: {
      outputDir: './source/images',
      prefixKey: '/images'
    }
  },
}

语雀配置

Token 模式或者账号密码模式二选一即可，默认为账号密码模式，如果需要切换为 Token 模式，则修改platform为yuque即可

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
write: {
    platform: 'yuque-pwd',
    yuque: { // Token 模式
      token: process.env.YUQUE_TOKEN,
      login: process.env.YUQUE_LOGIN,
      repo: process.env.YUQUE_REPO,
      onlyPublic: false,
      onlyPublished: true,
    },
    "yuque-pwd": { // 账号密码模式
      username: process.env.YUQUE_USERNAME,
      password: process.env.YUQUE_PASSWORD,
      login: process.env.YUQUE_LOGIN,
      repo: process.env.YUQUE_REPO,
      linebreak: false
    }
  },
  • token为语雀Token，可从此处获取
  • username为语雀账号，一般为手机号
  • password为语雀登录密码，如果没有设置过，可在账号设置中进行设置
  • login为语雀路径，可从此处获取
  • repo为语雀仓库短名称，可从此处获取
  • onlyPublic表示是否只下载互联网公开文档
  • onlyPublished表示是否只下载已发布文档

本地配置

1
2
3
4
5
6
7
8
9
10
11
local: {
  outputDir: './source/_posts',
    filename: 'title',
    format: 'markdown',
    catalog: false,
    frontMatter: {
      enable: true,
      include: ['categories', 'tags', 'title', 'date', 'updated', 'permalink', 'cover', 'description'],
      timeFormat: true,
    }
}
  • outputDir表示文档的存放位置为项目根目录下的docs/docs文件夹中
  • filename表示文档将以数据库的 title 字段命名，也就是文档名
  • format表示文档将以 markdown 的形式保存
  • frontMatter.enable表示在 markdown 文档开头添加 Front Matter
  • frontMatter.include表示只输出数组中存在的字段，数据库的其他字段忽略

图床配置

1
2
3
4
local: {
  outputDir: './source/images',
  prefixKey: '/images'
}
  • outputDir表示图片的存放位置为项目根目录下的source/images文件夹中
  • prefixKey=/images表示图片的统一前缀为/images，因为 Hexo 会将source/images文件夹视为静态资源根目录，统一将图片放在这里，并指定图片前缀，Hexo 才能找到此图片

更多 Elog 配置详情，请阅读 Elog 文档

发表于 更新于

快速开始

前言

当前支持语雀 Token 模式（需要语雀超级会员）和账号密码模式（不需要任何会员）

文档站点工具汇总

  • 写作平台：语雀
  • 文档平台：Hexo
  • 博客主题：Next
  • 文档同步：Elog
  • 部署平台：Vercel

文档站点搭建指南

Fork模板仓库

点击 Fork 该模板仓库到个人 Github 账号仓库下并 clone 到本地。

安装依赖

在项目根目录下运行命令安装依赖：

1
npm install

新建本地调试文件

在项目根目录中复制.elog.example.env文件并改名为.elog.env，此文件将用于本地同步文档时使用。

配置语雀

参考示例知识库，选择或新建语雀文档知识库，并按照文档提示配置语雀并获取token login repo。并在本地.elog.env中写入。

Token 模式或者账号密码模式二选一即可，默认为账号密码模式，如果需要切换为 Token 模式，则修改elog.config.js中的platform为yuque

1
2
3
4
5
6
7
8
9
10
# 语雀（Token方式）
YUQUE_TOKEN=获取的Token

#语雀（账号密码模式）
YUQUE_USERNAME=一般是手机号
YUQUE_PASSWORD=登录密码

# 语雀公共参数
YUQUE_LOGIN=获取的login
YUQUE_REPO=获取的repo

本地调试

在项目根目录运行同步命令：

1
npm run sync:local

启动 Hexo

在项目根目录运行 Hexo 启动命令，打开本地链接。

1
npm run server

配置 Hexo 博客

根据 Hexo 文档和 next 主题配置文档，配置你的博客直到你满意为主，你也可以换别的主题，这里不做演示

提交代码到 github

本地访问没问题直接提交所有文件到 Github 仓库即可

部署到 Vercel

注册 Vercel 账号并绑定 Github，在 Vercel 导入 该项目，Vercel 会自动识别出该 VitePress 项目，不需要改动，直接选择 Deploy 部署。部署完成会有一个 Vercel 临时域名，你也可以绑定自己的域名。
image.png

自动化同步&部署

:::warning
注意：在非国内CI/CD环境中使用账号密码模式登录语雀，例如Github
Workflow，会导致语雀后台登录设备中出现大量美国IP，目前尚不清楚语雀是否会有安全限制措施，请谨慎使用。推荐本地同步时使用。
:::

检查 Github Actions 权限

在 Github 仓库的设置中找到 Actions-General，打开流水线写入权限Workflow permissions
image.png

配置环境变量

在本地运行时，用的是.elog.env文件中定义的语雀账号信息，而在 Github Actions 时，需要提前配置环境变量。
在 Github 仓库的设置中找到 Secrets and variables，新增仓库的环境变量和.elog.env保持一致即可
image.png

自动化部署

当在语雀中改动文档后，手动/自动触发 Github Actions流水线，会重新从语雀增量拉取文档，自动提交代码到 Github 仓库。
Vercel 会实时监测仓库代码，当有新的提交时都会重新部署博客。如此就实现了自动化部署博客。
整个流程的关键点就在于：如何手动/自动触发 Github Actions。
在项目.github/workflows/sync.yaml中已经配置了外部 API 触发 Github Actions 事件，所以只需要调用 API 触发流水线即可。

手动触发

为了方便，这里提供一个部署在 Vercel 的免费公用的ServerlessAPI，按照文档配置好 URL 参数并浏览器访问即可触发流水线

1
https://serverless-api-elog.vercel.app/api/github?user=xxx&repo=xxx&event_type=deploy&token=xxx

自动触发-语雀 webhooks

需要语雀专业会员

在语雀知识库 - 更多设置 - 消息推送中可配置语雀 webhooks，填写上面的 Vercel Serverless API。当文档更新时，语雀会调用这个API进行推送，进而触发 Github Actions

注意：语雀是国内文档平台，调用国外Vercel 的服务可能会失败，可自行部署 API

注意：知识库配置了「自动发布」功能后，文档的 更新/发布 操作暂不会发送 webhooks

参考示例

示例 Github 仓库：待完善
示例语雀知识库：https://www.yuque.com/1874w/yuque-hexo-template
示例文档站点：待完善

发表于 更新于

语雀示例文章

基础

1.图片

image.png

2.表格

字段 备注
name 名称
age 年龄

3.附件

测试文本1.docx

4.状态

计划中
未完成
已完成

布局和样式

1.高亮块

蓝色背景高亮块

灰色背景高亮

天蓝

翠绿

绿色

黄色

橙色

橙粉

粉色

紫色

2.折叠块

折叠标题折叠内容

3.分栏卡片

两列分栏——左
头像1.PNG
两列分栏——右

1
const a = 1

4.引用

引用文本第一行
引用文本第二行
引用文本第三行

5.分割线

6.表情

😃 🤪

画板类

1.画板

2.思维导图

3.流程图

数据表

程序员专区

1.代码块

1
2
3
4
5
6
// TypeScript
const test = (post: DocDetail) => {
	const newPost = process(post)
  return newPost
}
export default test
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Java
@Test
public void test11() {
    long start = System.currentTimeMillis();
    int a = 0;
    for(int i=0;i<1000000000;i++){
        try {
            a++;
        }catch (Exception e){
            e.printStackTrace();
        }
    }
    long useTime = System.currentTimeMillis()-start;
    System.out.println("useTime:"+useTime);
}

2.公式

3.UML图

4.文本绘图

小工具

1.提及

@1874(1874w)

2.内嵌语雀内容

快速开始

3.日历

4.投票

5.打卡

6.加密文本

嵌入本地内容

1.本地文件

测试文本1.docx

2.本地音频

3.本地视频

46_1677164223.mp4 (139.39KB)

第三方服务

1.优酷

点击查看【youku】

2.B站

点击查看【bilibili】

3.网易云

点击查看【music163】

4.ProcessOn

点击查看【processon】

5.Canva

点击查看【canva】

6.CodePen

点击查看【codepen】

7.码上掘金

点击查看【juejin】

0%