しました！
GitBookとは、GitHub上のmarkdown形式のファイルを色々な形式のドキュメントとして公開できるサービスです。
こちら、Web公開の他に静的なファイルも生成でき、オフラインの方向けにPDFを出力する需要があったんですよね。
じゃあせっかくなのでGitHub Actionsを使ってpushを連動させました！
この記事では、その実現方法とハマった点の解説をしていきます。GitBook自体の使い方については記載しないので、使い方を知りたい方はGitBookによるドキュメント作成などを参照ください。
yamlファイルはこれ！
以下をGitHub Actionsのworkflowにコミットすれば、GitHub Actionsのarchifactsのところに成果物ができます。以上！
name: Export PDF
on:
push:
branches: [ master ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install ubuntu package
sudo apt-get update && sudo apt-get install calibre
#install japanese font if your document is JP
sudo apt-get install fonts-takao-mincho fonts-takao
- name: Run PDF export
run: |
# install n to downgrade npm version
sudo npm install -g n
fixed_npm=`n ls-remote --all 10 | head -n 1`
# downgrade to 10.x
sudo n ${fixed_npm}
# install gitbok-cli and call
npm install gitbook-cli
./node_modules/.bin/gitbook pdf
- name: Archive pdf artifacts
uses: actions/upload-artifact@v2
with:
name: output.pdf
path: book.pdf
内容について解説していきます。
内容の解説！
大きな流れは以下。それぞれの要素について説明していきます。
- gitbook-cliを使用可能な状態にする！
- pdfを出力する！
- 成果物を保存する！
1. gitbook-cliを使用可能な状態にする！
基本的には手元のPCでPDF出力するのと同じ手順の環境構築が入ります。Install Calibreの手順で、Calibreをインストール。
後はgitbok-cliをnpm installして実行するだけ
...なはずが、GitHub Actionsでnpm install gitbook-cliするとこんなエラーに。
+ gitbook-cli@2.3.2
added 578 packages from 672 contributors in 11.858s
Installing GitBook 3.2.3
/home/runner/work/gitbook_repos/gitbook_repos/node_modules/npm/node_modules/graceful-fs/polyfills.js:287
if (cb) cb.apply(this, arguments)
ガッツリハマりました。
ググってみると同様のエラーが出ています。依存関係の問題であることは見えてたのですが、リンク記事に書いてある内容を試しても解決せず
TypeError: cb.apply is not a function
Gitbook build stopped to work in node 12.18.3 #110
最終的にはgitbook install時にエラーに記載されているnode.jsのversionを下げる方法で解決しました。
versionを下げる方法はこちらを参考に以下で実行。
10.xで動作している実績を見つけたため、その中で最新のversionを利用する形としてます。
# install n to downgrade npm version
sudo npm install -g n
fixed_npm=`n ls-remote --all 10 | head -n 1`
# downgrade to 10.x
sudo n ${fixed_npm}
また、日本語ドキュメントの場合はフォントがないので、フォントをインストールします。
sudo apt-get install fonts-takao-mincho fonts-takao
2. pdfを出力する！
gitbook-toolsの機能を使い、pdf出力します。
./node_modules/.bin/gitbook pdf
こんな感じのログが出た後、book.pdfが出力されます。
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 17 pages
info: found 279 asset files
info: >> generation finished with success in 47.7s !
info: >> 1 file(s) generated
3. 成果物を保存する！
GitHub Actionsのartifactsで成果物を保存できます。
ワークフロー データを成果物として保存する
ここのusesで指定したactions/upload-artifactが、成果物をアップロードするためのものとなります。
- name: Archive pdf artifacts
uses: actions/upload-artifact@v2
with:
name: output.pdf
path: book.pdf
アップロードできるデータの容量は上限があります。こちらで確認可能です。
GitHub Actions の使用状況を表示する
フリープランの場合は1GByteまでとなります。
参考！
GitBookの使い方: GitBookによるドキュメント作成
npm install gitbook-cliでハマった際の参考たち
TypeError: cb.apply is not a function
Gitbook build stopped to work in node 12.18.3 #110
gitbook install時にエラー
インストールしている Node.js のバージョンをダウングレードさせるために n を使ってみる
GitHub Actionsのartifacts
ワークフロー データを成果物として保存する
GitHub Actions の使用状況を表示する