この記事では、UMLも書けるHonKit環境をDockerで構築したのでご紹介します。
HonKitはMarkDown記法で記述できるドキュメント作成ツールです。
事の始まりは、個人開発でDDDを実践しようと仕様・設計をきちんとしたかたちで整理したいと思ったことでした。
業務でGitBookを使っているのですがサポートが切れているとのことで、後継であるHonKitを使って環境を整備することにしました。
要件
- UMLを記述できること
- 業務利用のGitBookでUMLを記述できて非常に快適だったため
実現方法
docker-composeでHonKit用のNode.jsコンテナとUML用のplantumlコンテナを用意して、Node.jsコンテナでHonkitを、plantumlコンテナでUMLをレンダリングするようにしました。
docker-compose.yml
version: '3.3'
services:
plantuml:
image: bitjourney/plantuml-service:1.4.2
honkit:
image: node:18.11-bullseye-slim
ports:
- 4000:4000
volumes:
- .:/app
- node_modules:/app/node_modules
tty: true
working_dir: /app
volumes:
node_modules:
plantumlコンテナはbitjourney/plantuml-serviceのイメージを使ってビルドするだけです。
HonKitコンテナはNode.jsのイメージを用います。
HonKitではローカルサーバーを立ち上げて4000ポートで接続してレンダリングを確認します。
そのためにホストの4000ポートをコンテナの4000ポートに接続します。
docker-compose.ymlと同じ階層にsrcディレクトリを作成し、その中にコンテンツを作成していきます。
作業場として作成する/appディレクトリにdocker-compose.ymlのある階層をマウントしています。
/appディレクトリは作業場なのでワーキングディレクトリに設定。
npm installした際に生成されるnode_modulesディレクトリはホスト側に反映されたくないので、node_modulesという名前付きボリュームをマウントすることで共有を防ぎました。
起動したコンテナは正常終了しないようにtty: trueを設定しています。
package
今回インストールしたパッケージは次のとおりです。
- gitbook-plugin-anchors
- gitbook-plugin-collapsible-chapters
- gitbook-plugin-hide-published-with
- gitbook-plugin-lb2b
- gitbook-plugin-plantuml-cloud
gitbook-plugin-anchors
見出しにアンカーリンクを作成できるようになります。
gitbook-plugin-collapsible-chapters
SUMMARY.md に記載されているサイドバーを折りたためるようになります。
▼ デフォルトのサイドバー
▼ collapsible-chaptersで閉じられている状態のサイドバー
▼ 開いている状態のサイドバー
gitbook-plugin-hide-published-with
デフォルトで表示される『HonKitで公開』を非表示にします。
▼ 表示状態
▼ 非表示状態
gitbook-plugin-lb2b
Markdown記法では改行するときに半角スペースを2つ入れないといけません。
このプラグインを用いることで、半角スペースを入れなくても改行を改行として扱えます。
▼ プラグイン適用前
▼ プラグイン適用後
gitbook-plugin-plantuml-cloud
UMLをレンダリングするためのプラグイン。
PlantUMLサーバーを用いてレンダリングします。
はじめはJavaのイメージを用いたHonKitのコンテナ内でレンダリングしていたのですが、日本語が文字化けしてしまったため、こちらの方法にしました。
ご覧のように、日本語も表示できています。
（UMLの横に表示される;が気になります…消す方法をご存じの方がいれば、コメントでご教示いただけると幸いです。）
book.json
{
"root": ".",
"plugins": [
"anchors",
"collapsible-chapters",
"hide-published-with",
"lb2br",
"plantuml-cloud"
],
"pluginsConfig": {
"plantuml-cloud": {
"protocol": "http",
"host": "plantuml",
"port": 1608,
"blockRegex": "^```p?uml((.*[\r\n])+?)?```$"
}
},
"language": "ja"
}
HonKitの設定は上記のとおりです。
book.jsonをsrcディレクトリ下に配置し、rootに"."を指定。
表示を日本語にするためにlanguageは"ja"を記載しています。
前述したpluginたちを指定し、pluginsConfigにplantuml-cloudの設定を記載します。
protocolは"html"を、hostはコンテナ名の"plantuml"を指定します。
portは1608で固定です。
blockRegexはUMLを記載するブロックの指定を行っています。
```pumlまたは ```umlから始まり、```で終わるところまでをPlantUMLとして認識するようにしています。
まとめ
この記事では、UMLも書けるHonKit環境をDockerで構築したのでご紹介しました。
PlantUMLサーバーのコンテナとHonKitサーバーのコンテナを用いることで、素早くレンダリングして内容を確認できる環境が出来上がりました。
紹介した環境はGitHub上に公開していますので、気になる方がいたらCloneしていただければと思います。