本記事は Yuque によって作成されました
「Yuque」は「知識創作ツール」であり、アリペイから孵化したもので、体験技術の理念に基づく革新的な製品です。すでに 5 万人以上のアリババ社員が文書作成や知識の蓄積に利用しています。ブロガーは元々Yuque のユーザーであり、偶然 elog を発見し、Yuque の記事をローカルに同期できることを知りました。Yuque で執筆することで、即時レンダリングが可能で、画像ホスティングも考慮する必要がありません。無駄話はさておき、以下にチュートリアルを始めます。
ブログ記事を Yuque に移行する#
Yuqueの公式サイトを開き、ホームページに入ります。左上のプラスボタンをクリックします。
次にインポート
をクリックします。
次に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(アカウント、パスワード方式)の 2 つの設定方法が提供されています。
Yuque のメンバーであれば、yuque(Token 方式)を選択することをお勧めします。そうでない場合は yuque-pwd(アカウント、パスワード方式)を選択してください。
elog.config.js ファイルを編集する#
module.exports = {
write: {
platform: 'yuque-pwd', // yuqueまたはyuque-pwdを記入
yuque: {
token: process.env.YUQUE_TOKEN, // 以下の3行の設定は変更しないでください。設定は.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 を追加することをお勧めします。
具体的な設定はあなたの設定方法によります。
以下に公式の文書の説明を直接引用します。
Yuque(Token 方式)#
注意:Yuque の価格に応じて、この方法は Yuque のプレミアムメンバーのみが利用可能です。以前にトークンを生成したアカウントは引き続き使用可能です。
Yuque の重要情報の取得と設定手順については、重要情報の取得ページをご覧ください。
フィールド | 必須 | 説明 | デフォルト値 |
---|---|---|---|
token | はい | Yuque トークン | - |
baseUrl | いいえ | Yuque API リクエストのベース URL | https://www.yuque.com/api/v2 |
login | はい | 個人パス / スペース ID | - |
repo | はい | Yuque リポジトリの短い名前、または Yuque ナレッジベースのパス | - |
onlyPublic | いいえ | 公開記事のみを取得するか | false |
onlyPublished | いいえ | 公開された記事のみを取得するか | false |
limit | いいえ | ドキュメントダウンロードの同時数 | 3 |
baseUrl は Yuque API リクエストのパスです。
ナレッジベースのタイプが個人ナレッジベースの場合、設定は不要です。
ナレッジベースのタイプがチームナレッジベースの場合、baseUrl=https:// スペース id.yuque.com/api/v2、login = スペース id、repo = スペース内の Yuque ナレッジベースのパスです。
Yuque(アカウントパスワード方式)#
この方法は Yuque のメンバーシップなしでも使用可能です。
注意:国内外の CI/CD 環境でこの方法を使用すると、Yuque のバックエンドに大量のアメリカ IP が表示される可能性があります。Yuque が安全制限措置を講じるかどうかは不明ですので、慎重に使用してください。ローカル同期時に使用することをお勧めします。
Yuque の重要情報の取得と設定手順については、重要情報の取得ページをご覧ください。
フィールド | 必須 | 説明 | デフォルト値 |
---|---|---|---|
username | はい | Yuque アカウント、通常は電話番号 | - |
password | はい | Yuque パスワード、設定でバインドできます | |
host | いいえ | Yuque ドメイン / チームドメイン | https://www.yuque.com |
login | はい | 個人パス / スペース ID | - |
repo | はい | Yuque リポジトリの短い名前、または Yuque ナレッジベースのパス | - |
linebreak | いいえ | Yuque の改行を保持するか | false |
onlyPublic | いいえ | 公開記事のみを取得するか | false |
onlyPublished | いいえ | 公開された記事のみを取得するか | false |
limit | いいえ | ドキュメントダウンロードの同時数 | 3 |
host は Yuque ドメインです。
ナレッジベースのタイプが個人ナレッジベースの場合、設定は不要です。
ナレッジベースのタイプがチームナレッジベースの場合、host=https:// スペース id.yuque.com
同期を開始する#
設定が完了したら、ルートディレクトリでローカル同期コマンドを実行します:
elog sync -e .elog.env
自動化プロセス#
Yuque + webhooks + serverless api + GitHub Actions + Github Pages の継続的インテグレーション
ここでは公式文書の内容を引用します。
#
GitHub Actions#
- リポジトリの Settings の Secrets and variables-Actions-Secrets で必要な環境変数を設定します。
GITHUBTOKEN | あなたの Github トークン |
---|---|
YUQUE_REPO | あなたの Yuque ナレッジベースのパス |
YUQUE_LOGIN | あなたの Yuque アカウント名(パス) |
YUQUE_USERNAME | あなたの電話番号 |
YUQUE_PASSWORD | あなたの Yuque パスワード |
Yuque(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: Yuqueの記事を取得
env:
# Yuque関連の環境変数
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を提供します。
これを Yuque の Webhooks に入力すれば OK です。
メンバーシップがない Yuque ユーザーは、この API を手動で呼び出して GitHub Actions をトリガーし、自動構築とデプロイを行うことができます。
https://serverless-api-elog.vercel.app/api/github?user=xxx&repo=xxx&event_type=xxx&tok
Yuque webhooks#
Yuque ナレッジベース - その他の設定 - メッセージプッシュで Yuque webhooks を設定できます。POST リクエストをサポートする API リンクを入力するだけです(ここでは serverless api を例にしています)。文書が更新されると、Yuque はこの API を呼び出してプッシュします。
残念ながら、Yuque は webhooks を有料化しました。
メンバーシップがない Yuque ユーザーは、この API を手動で呼び出して GitHub Actions をトリガーし、自動構築とデプロイを行うことができます。
ナレッジベースに「自動公開」機能が設定されている場合、文書の更新 / 公開操作は webhooks を送信しません。