Dockerで作るUMLも書けるHonKit環境

この記事では、UMLも書けるHonKit環境をDockerで構築したのでご紹介します。

[HonKit](https://github.com/honkit/honkit)はMarkDown記法で記述できるドキュメント作成ツールです。

事の始まりは、個人開発でDDDを実践しようと仕様・設計をきちんとしたかたちで整理したいと思ったことでした。
業務でGitBookを使っているのですがサポートが切れているとのことで、後継であるHonKitを使って環境を整備することにしました。

## 要件

- UMLを記述できること
    - 業務利用のGitBookでUMLを記述できて非常に快適だったため

## 実現方法

docker-composeでHonKit用のNode.jsコンテナとUML用のplantumlコンテナを用意して、Node.jsコンテナでHonkitを、plantumlコンテナでUMLをレンダリングするようにしました。

### docker-compose.yml

```yaml: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-anchors)
- [gitbook-plugin-collapsible-chapters](gitbook-plugin-collapsible-chapters)
- [gitbook-plugin-hide-published-with](gitbook-plugin-hide-published-with)
- [gitbook-plugin-lb2b](gitbook-plugin-lb2b)
- [gitbook-plugin-plantuml-cloud](gitbook-plugin-plantuml-cloud)

#### gitbook-plugin-anchors

https://www.npmjs.com/package/gitbook-plugin-anchors

見出しにアンカーリンクを作成できるようになります。

![アンカーリンク](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/281085/06a9b60b-64d8-2974-26fe-5bf0ea76cc86.png "アンカーリンク")


#### gitbook-plugin-collapsible-chapters

https://www.npmjs.com/package/gitbook-plugin-collapsible-chapters

SUMMARY.md に記載されているサイドバーを折りたためるようになります。

▼ デフォルトのサイドバー
![デフォルトのサイドバー](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/281085/7776fbc1-126a-e550-e3b1-99c5d73b9925.png "デフォルトのサイドバー")


▼ collapsible-chaptersで閉じられている状態のサイドバー
![collapsible-chaptersで閉じられているサイドバー](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/281085/30e7af80-adb2-fc68-b58d-7d61dcd49b08.png "collapsible-chaptersで閉じられているサイドバー")

▼ 開いている状態のサイドバー
![collashibleOpend.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/281085/01814a14-9c10-dcbf-edd9-1167d531a426.png)

#### gitbook-plugin-hide-published-with

https://www.npmjs.com/package/gitbook-plugin-hide-published-with

デフォルトで表示される『HonKitで公開』を非表示にします。

▼ 表示状態
![表示状態](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/281085/bcf55733-5c72-6290-23f9-1c579fd2c5ea.png "表示状態")

▼ 非表示状態
![非表示状態](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/281085/82b80e14-1ee8-8f7b-dea4-ae302cd4a1b9.png "非表示状態")

#### gitbook-plugin-lb2b

https://www.npmjs.com/package/gitbook-plugin-lb2br

Markdown記法では改行するときに半角スペースを2つ入れないといけません。
このプラグインを用いることで、半角スペースを入れなくても改行を改行として扱えます。

▼ プラグイン適用前
![プラグイン適用前](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/281085/89966114-e298-ca79-b8e5-f20bd0814e34.png "プラグイン適用前")

▼ プラグイン適用後
![プラグイン適用後](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/281085/cafb9fff-3035-aa2f-a854-384b536de6fa.png "プラグイン適用後")

#### gitbook-plugin-plantuml-cloud

https://www.npmjs.com/package/gitbook-plugin-plantuml-cloud

UMLをレンダリングするためのプラグイン。
PlantUMLサーバーを用いてレンダリングします。
はじめはJavaのイメージを用いたHonKitのコンテナ内でレンダリングしていたのですが、日本語が文字化けしてしまったため、こちらの方法にしました。

![UML](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/281085/ac12ddd8-612e-e15d-99df-82d60b94f284.png "UML")

ご覧のように、日本語も表示できています。
（UMLの横に表示される`;`が気になります…消す方法をご存じの方がいれば、コメントでご教示いただけると幸いです。）

### book.json

```json: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していただければと思います。

https://github.com/Soh1121/honkit-on-docker