Jetbrains WritersideでAlgoliaを使いながらGithub Pagesにデプロイした話

自分用の備忘録です。

## 概要
### 方針
公式ドキュメントにできるだけ従ってやります。

### 仕組み
1. Github ActionsがDockerをビルド
2. Docker内でレンダリングしたweb archiveを生成
3. github pagesにデプロイ

UbuntuのDockerでレンダリングしたHTMLを生成するので、他のサービスを導入することができます。今回は全文検索サービスでJetbrains公式でも連携をサポートしているAlgoliaにしました。

### ワークフローを組むときのコツ
基本は公式ドキュメントに従って進めれば良いのですが、
__以下の点は自分で変更・調整する必要があります。__
- instance ID
- API関係の環境変数
- Github Actions内で操作されるディレクトリ

## 本編
説明の都合上、以下の作業を行ったこととします。
1. Githubに新しいリポジトリを作る
2. ローカルリポジトリからinitial commitをpushして成功
3. Jetbrains Writersideをインストール・起動
4. ローカルにweb archiveを出力させて正常だったことを確認

なお、私は`JetBrains Product Pack for Students`を使っています。

### Algoliaのアカウント作成
https://algolia.com

↑にサインインしてください。設定はよしなに。
ただ、リージョンで東京は選べませんでした（昔は選べたみたいです）。
最初の`Get Start`は右上の`SKIP NOW`ボタンで飛ばせたら飛ばしてください（これもボタンが出ていないことがある）。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3874920/94c76b91-abfb-ca54-bc59-e50682eaaf4e.png)

しかしこのGet Startはデータがアップロードされないうちはずっと出てくることになります。ここで欲しい情報は`Application ID`, `Search API Key`, `Admin API Key`なので、一番下の方の"Wordpress"を表示しておくと良いです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3874920/9f9b9929-173d-4728-80b2-7c118885ce66.png)

それから、GithubのSettingsからシークレット変数としてAdmin API Keyを定義してください。
### ワークフロー作成
https://www.jetbrains.com/help/writerside/deploy-docs-to-github-pages.html

↑の公式ドキュメントに沿ってやります。基本的には公式ドキュメントで出ているワークフローをコピーしてきて環境変数を変える感じですね。ALGOLIA関係は`Writerside/cfg/buildprofiles.xml`の`Variables`タグ内にも記述してください。こんな感じになると思います。
```xml
    <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らしい）。
```yml
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でブログをデプロイしたい人がどれくらいいるかはわかりませんが）。