🥰

Honkit の多言語ドキュメントプロジェクトテンプレートを作りました

2021/07/16に公開

tex 数式,mermaid,eBook 出力に対応した Honkit の多言語ドキュメントプロジェクトに使えるようなテンプレートレポジトリを作りました.
レポジトリ右上の use this template から使えます.

honkit は azu さんが depracared になった gitbook をフォークして作ったプロジェクトです. gitbook の plugin をそのまま使えます.

便利なツールやプラグインを作ってくださった方々ありがとうございます❤

ローカルで実行する場合はビルドに少し時間がかかりますが docker-compose up 一発で立ち上がるようになっています. コンテナ化してあるので Windows/Mac 問わず使えるはずです.

2021/07現在、mermaid のプラグインにバグがあるので mermaid を使う場合は docker-compose exec book npm run patch を先に実行してください.

github page のデプロイのワークフローも用意してあるので、レポジトリの設定から gh-pages ブランチを指定すれば master に push するたびにページが公開されます.

また eBookの出力も可能です. 最新の calibre を入れてあります. 例えば、PDFの場合, 次のコマンドで現在のディレクトリ以下に example_ja.pdf とexample_en.pdf の両方が出力されます. ひとまず pdf については一通り動作確認しています.

docker-compose exec  --env QTWEBENGINE_CHROMIUM_FLAGS="--no-sandbox" book
 npx honkit pdf ./ ./example.pdf

コードハイライト,mermaidグラフと tex 数式の埋め込みが済んだ PDF が出力されます.

gitbook の plugin は更新が数年以上ストップしているものが多いので使うプラグインは最小限にしてあります. 必要に応じて npm i <plugin> と book.json の更新をしてください.

crowdin を使って自動翻訳できるようにしようかと思っていた矢先にこの記事が流れてきたのでやめました😇

次のような改善点があるのでPRをしてもらえると嬉しいです.

~~docker-compose up や docker-compose exec ... をする際に環境変数がみつかるときと見つからないときがあります. なじぇ....?(´･ω･｀)~~ mermaidのバグでした😖
脳死で Node と Python を乗っけているのでコンテナイメージが大きいです.
PDF 出力の際に, --no-sandbox を渡さないとエラーになります. Linux の sandbox issue というものらしいですが、もしなにか詳しいことを知っている方がいれば教えていただきたいです.
Dockerfile から github actions を作って pdf をアーティファクトとして出力するといいかもしれないです.