自分用の備忘録です。
概要
方針
公式ドキュメントにできるだけ従ってやります。
仕組み
- Github ActionsがDockerをビルド
- Docker内でレンダリングしたweb archiveを生成
- github pagesにデプロイ
UbuntuのDockerでレンダリングしたHTMLを生成するので、他のサービスを導入することができます。今回は全文検索サービスでJetbrains公式でも連携をサポートしているAlgoliaにしました。
ワークフローを組むときのコツ
基本は公式ドキュメントに従って進めれば良いのですが、
以下の点は自分で変更・調整する必要があります。
- instance ID
- API関係の環境変数
- Github Actions内で操作されるディレクトリ
本編
説明の都合上、以下の作業を行ったこととします。
- Githubに新しいリポジトリを作る
- ローカルリポジトリからinitial commitをpushして成功
- Jetbrains Writersideをインストール・起動
- ローカルにweb archiveを出力させて正常だったことを確認
なお、私はJetBrains Product Pack for Studentsを使っています。
Algoliaのアカウント作成
↑にサインインしてください。設定はよしなに。
ただ、リージョンで東京は選べませんでした（昔は選べたみたいです）。
最初のGet Startは右上のSKIP NOWボタンで飛ばせたら飛ばしてください（これもボタンが出ていないことがある）。
しかしこのGet Startはデータがアップロードされないうちはずっと出てくることになります。ここで欲しい情報はApplication ID, Search API Key, Admin API Keyなので、一番下の方の"Wordpress"を表示しておくと良いです。
それから、GithubのSettingsからシークレット変数としてAdmin API Keyを定義してください。
ワークフロー作成
↑の公式ドキュメントに沿ってやります。基本的には公式ドキュメントで出ているワークフローをコピーしてきて環境変数を変える感じですね。ALGOLIA関係はWriterside/cfg/buildprofiles.xmlのVariablesタグ内にも記述してください。こんな感じになると思います。
<variables>
<algolia-id>APPLICATION ID</algolia-id>
<algolia-index>INDEX_NAME</algolia-index>
<algolia-api-key>SEARCH_API_KEY</algolia-api-key>
</variables>
私のワークフローは以下のようになりました
（empty-topicのinstance IDはVらしい）。
name: Build and Deploy Documentation
on:
push:
branches: ["main"]
workflow_dispatch:
permissions:
id-token: write
pages: write
env:
INSTANCE: 'Writerside/v'
ARTIFACT: 'webHelpV2-all.zip'
DOCKER_VERSION: '241.18775'
ALGOLIA_ARTIFACT: 'algolia-indexes-V.zip'
ALGOLIA_APP_NAME: 'XXXXXXX'
ALGOLIA_INDEX_NAME: 'XXXXXXX'
ALGOLIA_KEY: '${{ secrets.ALGOLIA_KEY }}'
CONFIG_JSON_PRODUCT: 'V'
CONFIG_JSON_VERSION: '1.0'
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Build docs using Writerside Docker builder
uses: JetBrains/writerside-github-action@v4
with:
instance: ${{ env.INSTANCE }}
artifact: ${{ env.ARTIFACT }}
docker-version: ${{ env.DOCKER_VERSION }}
- name: Verify artifact generation
run: |
echo "Checking if necessary artifacts are generated..."
ls -l artifacts/
test -e artifacts/${{ env.ARTIFACT }} && echo "${{ env.ARTIFACT }} exists" || (echo "Error: ${{ env.ARTIFACT }} not found" && exit 1)
test -e artifacts/report.json && echo "report.json exists" || (echo "Error: report.json not found" && exit 1)
test -e artifacts/report.html && echo "report.html exists" || (echo "Error: report.html not found" && exit 1)
test -e artifacts/${{ env.ALGOLIA_ARTIFACT }} && echo "${{ env.ALGOLIA_ARTIFACT }} exists" || (echo "Error: ${{ env.ALGOLIA_ARTIFACT }} not found" && exit 1)
- name: Save artifact with build results
uses: actions/upload-artifact@v4
with:
name: docs
path: |
artifacts/${{ env.ARTIFACT }}
artifacts/report.json
artifacts/report.html
artifacts/${{ env.ALGOLIA_ARTIFACT }}
retention-days: 7
test:
needs: build
runs-on: ubuntu-latest
steps:
- name: Download artifacts
uses: actions/download-artifact@v4
with:
name: docs
path: artifacts
- name: Verify artifacts in test
run: |
echo "Verifying artifacts after download in test job..."
ls -l artifacts/
test -e artifacts/${{ env.ALGOLIA_ARTIFACT }} && echo "${{ env.ALGOLIA_ARTIFACT }} exists" || (echo "Error: ${{ env.ALGOLIA_ARTIFACT }} not found in test job" && exit 1)
- name: Test documentation
uses: JetBrains/writerside-checker-action@v1
with:
instance: ${{ env.INSTANCE }}
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
needs: [build, test]
runs-on: ubuntu-latest
steps:
- name: Download artifacts
uses: actions/download-artifact@v4
with:
name: docs
- name: Verify artifacts in deploy
run: |
echo "Verifying artifacts after download in deploy job..."
ls -l .
test -e ${{ env.ALGOLIA_ARTIFACT }} && echo "${{ env.ALGOLIA_ARTIFACT }} exists" || (echo "Error: ${{ env.ALGOLIA_ARTIFACT }} not found in deploy job" && exit 1)
- name: Unzip artifact
run: unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d dir
- name: Setup Pages
uses: actions/configure-pages@v5
- name: Package and upload Pages artifact
uses: actions/upload-pages-artifact@v3
with:
path: dir
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
publish-indexes:
needs: [build, test, deploy]
runs-on: ubuntu-latest
container:
image: registry.jetbrains.team/p/writerside/builder/algolia-publisher:2.0.32-3
steps:
- name: Download artifact
uses: actions/download-artifact@v4
with:
name: docs
- name: Unzip Algolia artifact
run: |
unzip -O UTF-8 -qq '${{ env.ALGOLIA_ARTIFACT }}' -d algolia-indexes
- name: Upload indexes to Algolia
run: |
env algolia-key='${{ env.ALGOLIA_KEY }}' java -jar /opt/builder/help-publication-agent.jar \
update-index \
--application-name '${{ env.ALGOLIA_APP_NAME }}' \
--index-name '${{ env.ALGOLIA_INDEX_NAME }}' \
--product '${{ env.CONFIG_JSON_PRODUCT }}' \
--version '${{ env.CONFIG_JSON_VERSION }}' \
--index-directory algolia-indexes/ \
2>&1 | tee algolia-update-index-log.txt
詰まったところ
-
unzipの時に
${{ env.ALGOLIA_ARTIFACT }}(algolia-indexes-V.zip)がないと怒られる- 基本的にdeploy部分を見直そう。Docker内ではArtifactsディレクトリにレンダリングされますが、レンダリングが終わるとルートディレクトリに移動されるようです。
-
なんかそもそもレンダリングされてない？
- 私はreport.htmlとalgolia-indexes-V.zipが謎にレンダリングされてませんでした。ワークフローを上述のものにしたら治ったので、根本原因は謎です・・・。
最後に
雑記帳的な感じですが、同じところで詰まってる人がいたら参考になれば嬉しいです（そもそもWritersideでブログをデプロイしたい人がどれくらいいるかはわかりませんが）。