利用语雀webhook作为静态博客的后端
语雀的编辑器体验是我知道在线的最优秀的。

尽量减少繁琐的事情,专注于书写

项目地址:yuque-webhook

特点

  • 利用语雀的webhook功能,无需token
  • 在语雀端即可完成基本的操作,无需配置服务器
    • 文档的编辑、更新和删除
    • hugo网站的配置以及主题的更换(无法实时自定义主题)
  • 支持大部分语雀编辑器的功能
    • 文本
    • 图片(利用img标签处理外链)
    • 思维导图,流程图,画板等
    • 附件(语雀更改了附件的规则,需要登录下载了)
    • B站和网易云
    • 第三方服务(利用ifame实现,需要启用渲染html的功能)
  • 支持多知识库,多人协作

尝试一下

托管于我自己的服务器上,请注意因为是webhook推送的文件,你的文档我可以看到,请不要push私密的文档。

  1. 语雀新建一个文档知识库
    1. 知识库的namespace为**zjan/blog**** **
    2. namespace可以在网页的url中获取,比如[https://www.yuque.com/zjan/bwcmnq](https://www.yuque.com/zjan/bwcmnq)那么知识库的namespace为zjan/bwcmnq
  2. 知识库右边有个三个点的知识库设置——更多设置——高级设置
    1. 开启自动发布去掉勾
    2. 自动发布无法触发wehhook
  3. 知识库右边有个三个点的知识库设置——更多设置——消息推送
  4. 选择其他渠道
    1. 机器人名字:任意即可,比如blog
    2. Webhook地址:https://webhook.529213.xyz/yuque?&namespace=<user>-<repo>&code=<任意字符串>&action=new
      1. <user>: 上面的zjan
      2. <repo>: 上面的bwcmnq
      3. code: 任意的字符串,比如abc123
      4. 例如:[https://webhook.529213.xyz/yuque?&namespace=zjan-bwcmnq&code=](https://webhook.529213.xyz/yuque?&namespace=<user>-<repo>&code=<)abc123&action=new
    3. 动态推送勾选以下几个后点击添加
      1. 发布文档
      2. 更新文档
      3. 新增评论(用于拉起删除文档的webhook)
    4. 点击已添加推送中的测试操作
    5. 稍等30s
webhook.png
  1. 访问https://<user>-<repo>.529213.xyz看看效果,例如我的https://zjan-bwcmnq.529213.xyz
  2. Enjoy!不出意外已经初始化好一个hugo生成的网站了,你可以在本知识库下编写文档了,和正常书写hugo文档一样,也可以使用Front Matter,当你编写完的时候点击发布稍等就可以看到已经渲染好了。
  3. 本编文档即为语雀编写,你可以看下对比的效果
    1. 语雀
    2. 博客

安装服务端

要求

  • Python3.8+
  • Hugo
  • git
  • 能访问到github.com
  • 以上均在环境变量中

配置虚拟环境并拉取代码

$ git clone https://github.com/SenLief/yuque-webhook.git # 拉取代码
$ python3 -m venv ~/.venv #配置虚拟环境
$ source ~/.venv/bin/activate #激活虚拟环境
$ cd yuque-webook
$ pip3 install -r requirements.txt #安装模块

配置.env

$ vim .env

BASEDIR=/home/<usr>/blog
GEN=hugo
DOMAIN=529213.xyz

BASEDIR:博客存放的位置,请确认用户有权限。
GEN:默认为hugo,如果更换其他的静态生成工具需要自己更改一下。
DOMAIN: 主要是托管的域名,不配置,初始化后可能打不开网站,需要配置好主题才行。

启用Webhoo监听服务

(可选)自用

如果只是自己用的话,可以直接在服务器配置,很容易配置

  1. 编辑config.json配置文件
# 直接修改配置文件,不要复制这个
{
      "blog": {                                                     # 配置prefix
            "code": "123456",																				# 字符串
            "basedir": "/home/www/test",                           # 博客放在哪个目录
            "desdir": "/home/www/test/zjan-bwcmnq/content/posts",  # 语雀的文档默认下载的目录
            "workdir": "/home/www/test/zjan-bwcmnq",               # hugo命令执行的目录
            "cmd": "hugo",                                          # 默认值hugo
            "conf": {
                  "html": true,                                     # 语雀图片防盗链需要,同时主题需要打开渲染html功能
                  "shortcode": false                                # hugo的shortcode特性,后续会渲染语雀的第三方服务
            }
      }
}
  1. 配置环境变量
    1. $ export NAMESPACE=<PREFIX>, 就是上边配置的那个blog
    2. $ export CODE=<code>,就是上文中的123456
  2. 初始化网站
    1. $ python3 tasks.py
    2. 你可以在$basedir目录下找到这个网站。
  3. 启动监听服务
    1. python3 app.py默认监听8080端口,冲突修改app.py

托管

可以在语雀上 完成基本的初始化网站,更换主题,配置文件,静态文件等操作,同时支持其他人一起用。

$ python3 app.py 默认监听默认监听8080端口,冲突修改app.py

配置Nginx反代服务

默认使用IP:PORT提供服务,同时如果多人使用,就无法区分了,所以可以利用nginx反代。

  1. 反代Webhook服务配置文件示例

server
{
    listen 80;
    listen 443 ssl http2;
    server_name webhook.529213.xyz;
    index index.php index.html index.htm default.php default.htm default.html;
    root /var/www/html;


    if ($server_port !~ 443){
        rewrite ^(/.*)$ https://$host$1 permanent;
    }
    #HTTP_TO_HTTPS_END
    ssl_certificate    /etc/ssl/fullchain.cer;
    ssl_certificate_key    /etc/ssl/senlief.xyz.key;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:HIGH:!aNULL:!MD5:!RC4:!DHE;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    error_page 497  https://$host$request_uri;

    #SSL-END

    location / {
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   Host      $http_host;
        proxy_pass         http://127.0.0.1:8080;
        proxy_set_header REMOTE-HOST $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 100m;
        }
}
  1. 二级域名泛解析配置示例

需要把*解析到服务器的IP上


server
{
    listen 80;
    listen 443 ssl http2;
    server_name ~^(?<subdomain>.+).529213.xyz$;
    index index.php index.html index.htm default.php default.htm default.html;
    root /var/www/html;


#    if ($server_port !~ 443){
#        rewrite ^(/.*)$ https://$host$1 permanent;
#    }
#    #HTTP_TO_HTTPS_END
#    ssl_certificate    /etc/ssl/fullchain.cer;
#    ssl_certificate_key    /etc/ssl/senlief.xyz.key;
#    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
#    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:HIGH:!aNULL:!MD5:!RC4:!DHE;
#    ssl_prefer_server_ciphers on;
#    ssl_session_cache shared:SSL:10m;
#    ssl_session_timeout 10m;
    error_page 497  https://$host$request_uri;

    #SSL-END

    location / {
        root /home/www/blog/$subdomain/public;
        index index.html;
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
        add_header Access-Control-Allow-Headers 'DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization';

        if ($request_method = 'OPTIONS') {
           return 204;
        }
     }
}

语雀端配置

配置webhook推送

查看上面的尝试一下,配置是相同的,只需要稍微修改一下。

  1. webhook地址:修改为你自己配置的webhook前缀,替换掉上面的webhook.529213.xyz即可
  2. namespace:这是一个不重复的字符串,也是二级域名的前缀,建议使用语雀的namespace,例如zjan-blog,注意如果是自己服务器配置的config.json那么这里需要写blog
  3. code:一个鉴别用途的字符串,以防其他人利用同一个地址推送。注意如果是自己服务器配置的config.json那么这里需要写123456
  4. action:一些控制的动作
    1. new:初始化一个hugo的网站,配置后点击测试操作触发部署。
    2. deleted:删除部署过的网站
  5. 最后的webhook地址https://<你的webhook地址>/yuque?namespace=<string>&code=<string>&action=new
  6. 点击测试,稍等30s即可访问二级域名看看效果
  7. 注意:服务器需要能链接github下载主题,如果不能会clone失败

配置主题和配置文件

  1. 知识库下新建一个文档,标题名为_blog_config
  2. 点击config模板,另存为模板或者复制到自己的知识库去
  3. ---横线把文档分为三个部分,分别配置主题主题的配置文件常用静态文件
    1. 主题,目前只支持从github下载主题。
      1. gen默认的不用管
      2. theme主题的名字,注意下载的文件夹就是这个名字。
      3. theme_url主题的github链接
      4. staticdir静态文件放置的文件夹,相对路径。
    2. 主题的配置文件,支持yamltoml记得切换语雀的语言高亮格式为yaml或者toml
    3. 常用静态文件例如favicon.ico
      1. 修改一下本地图片的名字,让后上传到语雀即可,会自动下载到上面的staticdir
      2. 注意多附图的每两个图片之间空一行 ** **
屏幕截图2022-04-12222426.png

语雀管理文档

发布文档

目前基本上支持了语雀大部分的编辑器特性

  1. 插入Front Matter
    1. 可以插入模板
    2. 默认已经有titledate自动生成,不要再写
    3. Front必须在首行
    4. 如果只需要titledate可以不写Front Matter 会自动插入
  2. 写作
    1. 文字的书写全部支持,可能会有部分的换行渲染有问题。
    2. 需要换行的地方请多敲一个空格或者回车,解析就可以了,尤其是2副连着的图片,或者一段文字直接插入一张图片,需要在文字后面多敲一个空格或回车。
    3. 支持的卡片(图片,附件类需要配置防盗链
      1. 图片
      2. 附件(有时候需要登录)
      3. 画板
      4. 表格(不支持合并,颜色)
      5. 画板
      6. 思维导图
      7. UML图
      8. 流程图
      9. 文本绘图
      10. 公式
      11. 代码块
      12. B站
      13. 网易云音乐
      14. 第三方的服务支持(利用iframe实现,样式可能会有些问题。)
    4. 点击发布Enjoy!

更新文档

  • 直接在文档中更新即可,更新后点击更新,会自动触发部署

删除文档

语雀没有提供api,所以目前利用新增评论触发

  1. 我不想删除语雀上的文件,只想让hugo不渲染
    1. 在Front matter中使用draft: true
  2. 我想要保留服务器的渲染,但是语雀上删除
    1. 直接在语雀上删除
    2. 注意:如果下次初始化文档,那么这篇文档也会被删除,需要提前备份
  3. 我想语雀和服务都删除
    1. 在需要删除的文档中评论#closed服务器会删除这篇文档并渲染
    2. 然后在语雀上删除即可

使用目录管理

由于没有用token,所以拿不到目录的信息,默认会全部下载到配置的目录中,比如默认的posts目录,对于确实有需要的,可以配置一下front来实现。

在front中添加一个path: about即可

这样就会把这篇文档下载到content/about目录,对于创建单页比较有用。

注意事项

  • 目前不支持文档的移动,如果移动了,需要重新初始化文档或者新建一个文档,把需要移动的内容复制过去,然后再删除。

最后修改于 2022-04-19