语雀富文本写作自动部署到 Hexo-工具盒子

本文章由语雀编写

「语雀」是一个「知识创作工具」，孵化自蚂蚁金服，是体验科技理念下的一款创新产品，已是 5万+ 阿里员工进行文档编写、知识沉淀的标配。博主本来就是语雀的用户，偶然发现下了elog，可以将语雀的文章同步到本地。用语雀写作除了能够即使渲染之外，并且图床也不用考虑了。废话不多说了下面开始教程。

迁移博客文章到语雀 {#迁移博客文章到语雀}

打开语雀官网进入首页，点击左上角加号

其次点击 `` 导入 `` 然后选择 `` markdown `` 格式最后在markdown导入配置中选择 `` markdown打包后的压缩文件 `` 导入完成后文件的Front-matter有点乱建议自己手动更改下

安装 Elog {#安装-elog}

首先，你需要使用 npm/ cnpm / yarn / pnpm 全局安装@elog/cli 自动换行复制

                  # 使用 npm 安装 CLI
npm install @elog/cli -g

使用cnpm 安装 CLI
=============



cnpm install @elog/cli -g


使用 yarn 安装 CLI
==============



yarn global add @elog/cli


使用 pnpm 安装 CLI
==============



pnpm install @elog/cli -g


安装指定版本
======



npm install @elog/cli@0.9.0 -g


也可使用 npx 运行 elog 的所有命令：将本文档使用 elog 命令的地方换成 npx @elog/cli
========================================================



例如
===



初始化 elog 配置文件
=============



npx @elog/cli init


本地同步命令
======



npx @elog/cli sync -e .elog.env


清除本地缓存
======



npx @elog/cli clean


                </code>
                <!--]-->              </pre>

配置package.json {#配置packagejson}

将@elog/cli安装到package.json 自动换行复制

                  npm i @elog/cli
或者
cnpm i @elog/cli
或者
yarn add @elog/cli
或者
pnpm i @elog/cli

                </code>
                <!--]-->              </pre>

初始化 {#初始化}

进入Hexo根目录下，使用命令进行初始化：自动换行复制

                  elog init

                </code>
                <!--]-->              </pre>

根据提示初始化成功后，会在根目录生成一份 elog.config.js 配置文件和本地调试用的.elog.env环境变量配置文件。

配置Elog {#配置elog}

官方文档提供两种配置方式yuque（Token方式）和yuque-pwd（账号、密码方式）如果你是语雀的会员建议选择yuque（Token方式，反之则选择yuque-pwd（账号、密码方式）

编辑你的elog.config.js文件 {#编辑你的elogconfigjs文件}

自动换行复制

                  module.exports = {
  write: {
    platform: 'yuque-pwd', // 填yuque或yuque-pwd
    yuque: {
      token: process.env.YUQUE_TOKEN, // 以下三行配置不用动，配置都写在.elog.env 
      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,
      onlyPublic: false,
      onlyPublished: true,
    },
    notion: {
      token: process.env.NOTION_TOKEN,
      databaseId: process.env.NOTION_DATABASE_ID,
      filter: false, // {property: 'status', select: {equals: '已发布'}}
    },
    feishu: {
      type: 'space',
      wikiId: process.env.FEISHU_WIKI_ID,
      folderToken: process.env.FEISHU_FOLDER_TOKEN,
      appId: process.env.FEISHU_APP_ID,
      appSecret: process.env.FEISHU_APP_SECRET,
    },
    flowus: {
      tablePageId: process.env.FLOWUS_TABLE_PAGE_ID,
      filter: false, // {property: 'status',value: '已发布'}
    }
  },
  deploy: {
    platform: 'local',
    local: {
      outputDir: './source/_posts/yuque',  \\ 文件同步目录
      filename: 'title', 
      format: 'matter-markdown', \\ md文件带上Front-matter
    },
    halo: {
      endpoint: process.env.HALO_ENDPOINT,
      token: process.env.HALO_TOKEN,
      policyName: process.env.HALO_POLICY_NAME,
      rowType: 'html',
      needUploadImage: true,
    },
    confluence: {
      user: process.env.CONFLUENCE_USER,
      password: process.env.WORDPRESS_PASSWORD,
      endpoint: process.env.WORDPRESS_ENDPOINT,
      spaceKey: process.env.CONFLUENCE_SPACE_KEY,
      rootPageId: process.env.CONFLUENCE_ROOT_PAGE_ID, // 可选
    },
    wordpress: {
      username: process.env.WORDPRESS_USERNAME,
      password: process.env.WORDPRESS_PASSWORD,
      endpoint: process.env.WORDPRESS_ENDPOINT,
    }
  },
  image: {
    enable: false,
    platform: 'local',
    local: {
      outputDir: './docs/images',
      prefixKey: '/images',
      pathFollowDoc: false,
    },
    oss: {
      secretId: process.env.OSS_SECRET_ID,
      secretKey: process.env.OSS_SECRET_KEY,
      bucket: process.env.OSS_BUCKET,
      region: process.env.OSS_REGION,
      host: process.env.OSS_HOST,
      prefixKey: '',
    },
    cos: {
      secretId: process.env.COS_SECRET_ID,
      secretKey: process.env.COS_SECRET_KEY,
      bucket: process.env.COS_BUCKET,
      region: process.env.COS_REGION,
      host: process.env.COS_HOST,
      prefixKey: '',
    },
    qiniu: {
      secretId: process.env.QINIU_SECRET_ID,
      secretKey: process.env.QINIU_SECRET_KEY,
      bucket: process.env.QINIU_BUCKET,
      region: process.env.QINIU_REGION,
      host: process.env.QINIU_HOST,
      prefixKey: '',
    },
    upyun: {
      user: process.env.UPYUN_USER,
      password: process.env.UPYUN_PASSWORD,
      bucket: process.env.UPYUN_BUCKET,
      host: process.env.UPYUN_HOST,
      prefixKey: '',
    },
    github: {
      token: process.env.GITHUB_TOKEN,
      user: process.env.ELOG_GITHUB_USER,
      repo: process.env.ELOG_GITHUB_REPO,
      prefixKey: '',
    }
  }
}

                </code>
                <!--]-->              </pre>

配置.elog.env文件 {#配置elogenv文件}

为了防止此文件在Git上传中泄露建议在.gitignore中添加.elog.env

具体配置看你的设置方式下面直接引入官方的文档说明

语雀（Token方式） {#语雀token方式}

注意：根据语雀定价调整，此方式需要语雀高级会员可用，以前生成过token的账户依旧可用语雀关键信息获取及配置流程请移步关键信息获取页面。
自动换行

| 字段 | 必填 | 说明 | 默认值 | |---------------|--------|--------------------|--------------------------------| | token | 是 | 语雀Token | - | | baseUrl | 否 | 语雀API请求的Base Url | https://www.yuque.com/api/v2 | | login | 是 | 个人路径/空间ID | - | | repo | 是 | 语雀仓库短名称，也称为语雀知识库路径 | - | | onlyPublic | 否 | 是否只获取公开文章 | false | | onlyPublished | 否 | 是否只获取已发布文章 | false | | limit | 否 | 文档下载并发数 | 3 |

baseUrl 为语雀 API 请求路径当知识库类型为个人知识库时，无需配置。当知识库类型为团队知识库时，baseUrl= https://空间id.yuque.com/api/v2，login=空间id，repo=空间中的语雀知识库路径

语雀（账号密码方式） {#语雀账号密码方式}

此方式无需语雀会员也可用注意：在非国内CI/CD环境中使用此方式，例如Github Workflow，会导致语雀后台登录设备中出现大量美国IP，目前尚不清楚语雀是否会有安全限制措施，请谨慎使用。推荐本地同步时使用。语雀关键信息获取及配置流程请移步关键信息获取页面。
自动换行

| 字段 | 必填 | 说明 | 默认值 | |---------------|--------|--------------------|-------------------------------------------------| | username | 是 | 语雀帐号，一般是手机号 | - | | password | 是 | 语雀密码，可在设置进行绑定 | | | host | 否 | 语雀域名/团队域名 | https://www.yuque.com | | login | 是 | 个人路径/空间ID | - | | repo | 是 | 语雀仓库短名称，也称为语雀知识库路径 | - | | linebreak | 否 | 是否保持语雀的换行 | false | | onlyPublic | 否 | 是否只获取公开文章 | false | | onlyPublished | 否 | 是否只获取已发布文章 | false | | limit | 否 | 文档下载并发数 | 3 |

host 为语雀域名当知识库类型为个人知识库时，无需配置。当知识库类型为团队知识库时，host= https://空间id.yuque.com

开始同步 {#开始同步}

配置完成后在根目录下，执行本地同步命令：自动换行复制

                  elog sync -e .elog.env

                </code>
                <!--]-->              </pre>

自动化流程 {#自动化流程}

语雀 + webhooks + serverless api + GitHub Actions + Github Pages 持续集成 这里引用官方文档的内容 ``

Github Actions {#github-actions}

在仓库的Settings 中的Secrets and variables-Actions-Secrets中进行配置需要用到的环境变量

自动换行

| GITHUBTOKEN | 你的Github Token | |----------------|----------------| | YUQUE_REPO | 你的语雀知识库路径 | | YUQUE_LOGIN | 你的语雀账号名（路径） | | YUQUE_USERNAME | 你的手机号 | | YUQUE_PASSWORD | 你的语雀密码 |

如何你使用的是语雀（Token方式）可将YUQUE_USERNAME，YUQUE_PASSWORD换成YUQUE_TOKEN

在仓库根目录创建.github/workflows/Deploy Yuque-Hexo Public To Pages文件，并按照以下流程配置

自动换行复制

                  name: Deploy Yuque-Hexo Public To Pages

on:


允许手动push触发
==========



push:
branches:
- main


允许外部仓库事件触发
==========



repository_dispatch:
types:
# api中的event_type就是这个
- deploy


jobs:
build:
runs-on: ubuntu-latest


    steps:
      - name: 检查分支
        uses: actions/checkout@master

      - name: 安装node环境
        uses: actions/setup-node@master
        with:
          node-version: "16.x"

      - name: 安装Hexo并使用elog
        run: |
          export TZ='Asia/Shanghai'
          npm install hexo-cli -g
          npm install 
          npm run elog      
          hexo generate

      - name: 拉取语雀文章
        env:
          # 语雀相关环境变量
          YUQUE_TOKEN: ${{ secrets.YUQUE_TOKEN }}
          YUQUE_USERNAME: ${{ secrets.YUQUE_USERNAME }}
          YUQUE_PASSWORD: ${{ secrets.YUQUE_PASSWORD }}
          YUQUE_LOGIN: ${{ secrets.YUQUE_LOGIN }}
          YUQUE_REPO: ${{ secrets.YUQUE_REPO }}
        run: |
          # 对应package.json中的script.sync
          elog sync -e .elog.env

      - name: 配置Git用户名邮箱
        run: |
          git config --global user.name "xxxx"
          git config --global user.email "xxxx"

      - name: 提交yuque拉取的文章到GitHub仓库
        run: |
          echo `date +"%Y-%m-%d %H:%M:%S"` begin &gt; time.txt
          git add .
          git commit -m "更新文档" -a

      - name: 推送文章到仓库
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.secrets.GITHUBTOKEN }}



      - name: 部署到Github Pages       #此处master:master 指从本地的master分支提交到远程仓库的master分支，若远程仓库没有对应分支则新建一个。如有其他需要，可以根据自己的需求更改。
        run: |
          cd ./public
          git init
          git add .
          git commit -m "${{ github.event.head_commit.message }} $(date +"%Z %Y-%m-%d %A %H:%M:%S") Updated By Github Actions"
          git push --force --quiet "https://${{ github.repository_owner }}:${{ secrets.GITHUBTOKEN }}@github.com/${{ github.repository_owner }}/${{ github.repository_owner }}.github.io.git" master:master


                </code>
                <!--]-->              </pre>

访问serverless api可触发action部署

serverless api {#serverless-api}

为了方便，这里提供一个部署在Vercel的免费公用的 ServerlessAPI 将其填入语雀Webhooks中即可未开通会员的语雀小伙伴可直接手动调用此API触发Github Actions进行自动化构建&部署自动换行复制

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

                </code>
                <!--]-->              </pre>

语雀 webhooks {#语雀-webhooks}

在语雀知识库 - 更多设置 - 消息推送中可配置语雀webhooks，填写一个支持POST请求的APi链接即可（这里以serverless api为例）。当文档更新时，语雀会调用这个API进行推送令人遗憾的是，语雀将 webhooks 收费了未开通会员的语雀小伙伴可直接手动调用API触发Github Actions进行自动化构建&部署知识库配置了「自动发布」功能后，文档的更新/发布操作暂不会发送 webhooks