本文章由語雀編寫
「語雀」是一個「知識創作工具」,孵化自 蚂蚁金服 ,是 体验科技 理念下的一款創新產品,已是 5 萬 + 阿里員工進行文檔編寫、知識沉澱的標配。博主本來就是語雀的用戶,偶然發現下了 elog,可以將語雀的文章同步到本地。用語雀寫作除了能夠即時渲染之外,並且圖床也不用考慮了。廢話不多說了下面開始教程。
遷移博客文章到語雀#
打開語雀官網進入首頁,點擊左上角加號
其次點擊導入
然後選擇markdown
格式
最後在 markdown 導入配置中選擇markdown打包後的壓縮文件
導入完成後文件的 Front-matter 有點亂建議自己手動更改下
安裝 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/[email protected] -g
# 也可使用 npx 運行 elog 的所有命令:將本文檔使用 elog 命令的地方換成 npx @elog/cli
# 例如
# 初始化 elog 配置文件
npx @elog/cli init
# 本地同步命令
npx @elog/cli sync -e .elog.env
# 清除本地緩存
npx @elog/cli clean
配置 package.json#
將 @elog/cli 安裝到 package.json
npm i @elog/cli
或者
cnpm i @elog/cli
或者
yarn add @elog/cli
或者
pnpm i @elog/cli
初始化#
進入 Hexo 根目錄下,使用命令進行初始化:
elog init
根據提示初始化成功後,會在根目錄生成一份 elog.config.js 配置文件和本地調試用的.elog.env 環境變量配置文件。
配置 Elog#
官方文檔提供兩種配置方式 yuque(Token 方式)和 yuque-pwd(帳號、密碼方式)
如果你是語雀的會員建議選擇 yuque(Token 方式,反之則選擇 yuque-pwd(帳號、密碼方式)
編輯你的 elog.config.js 文件#
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: '',
}
}
}
配置.elog.env 文件#
為了防止此文件在 Git 上傳中洩露建議在.gitignore 中添加.elog.env
具體配置看你的設置方式
下面直接引入官方的文檔說明
語雀(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
自動化流程#
語雀 + webhooks + serverless api + GitHub Actions + Github Pages 持續集成
這裡引用官方文檔的內容
#
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 > 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
訪問 serverless api 可觸發 action 部署
serverless api#
為了方便,這裡提供一個部署在 Vercel 的免費公用的ServerlessAPI
將其填入語雀 Webhooks 中即可
未開通會員的語雀小夥伴可直接手動調用此 API 觸發 Github Actions 進行自動化構建 & 部署
https://serverless-api-elog.vercel.app/api/github?user=xxx&repo=xxx&event_type=xxx&tok
語雀 webhooks#
在語雀知識庫 - 更多設置 - 消息推送中可配置語雀 webhooks,填寫一個支持 POST 請求的 APi 鏈接即可(這裡以 serverless api 為例)。當文檔更新時,語雀會調用這個 API 進行推送
令人遺憾的是,語雀將 webhooks 收費了
未開通會員的語雀小夥伴可直接手動調用 API 觸發 Github Actions 進行自動化構建 & 部署
知識庫配置了「自動發布」功能後,文檔的 更新 / 發布 操作暫不會發送 webhooks