MkDocsでPlantUMLを表示させる

自分はドキュメントを書く際にはPlantUMLを結構使います。
ちょっと久々に結構な量のドキュメントを書く必要性が出てきたのでMkDocsで環境整えようと思ったときに躓いたので備忘録。

環境はすべてdockerで作成します。

dockerで環境を整える

PlantUML Serverを建てる

今回の本筋ではないのですが、念の為立て方を書いておきます。
以下をyamlファイルを用意してdocker-compose up -d でPlantUML Serverを起動させておきます。

version: "3.7"

services:
  plantuml:
    image: plantuml/plantuml-server
    ports:
      - 18080:8080

サーバが起動してブラウザでアクセスし、以下のようなページが表示されればOKです。
ここで、サーバのIPアドレスは 192.168.1.100 とし、ページは http://192.168.1.100:18080 でアクセスできるものとし説明を続けます。

MkDocsのコンテナ環境を作成する

MkDocs用のコンテナのDockerfileは以下になります。
公式のpythonのdockerイメージをベースに使用するパッケージを追加します。
今回はMkDocsをマテリアルデザインのテーマとPlantUMLを使えるようにするだけにとどめてあります。

FROM python:3-buster

WORKDIR /

RUN pip install -U \
        pip \
        mkdocs \
        mkdocs-material \
        plantuml-markdown \
    && mkdocs new docroot

WORKDIR /docroot

次に、docker-compose.yamlは以下になります。
docroot のディレクトリは mkdocs new で作成したMkDocsのプロジェクトのディレクトリをローカルに保持してマウントするようにしています。
コンテナを起動すると mkdocs serve でサーバが起動するようにしています。
http://192.168.1.100:18000 でアクセスするとページが表示されます。
単純に mkdocs serve だけだとlocalhost:8000 でlistenするのでコンテナ外からアクセスできません。
そのため、コンテナ外からアクセスできるように -a のオプションを追加しています。

version: "3.7"

services:
  mkdocs:
    build:
      context: ./
      dockerfile: ./Dockerfile
    volumes:
      - ./docroot:/docroot
    ports:
      - 18000:8000
    tty: true
    command: bash -c "mkdocs serve -a 0.0.0.0:8000"

PlantUMLと連携する

PlantUML と連携するためには以下の準備が必要です。

• plantuml-markdown のインストール
• mkdocs.yml にplantuml_markdownのextensionの追加

plantuml-markdownのインストールはDockerfile ですでに済んでいるため割愛します。

plantuml_markdown のextensionの追加

mkdocs.yml に以下を追加します。
以前だと、serverに設定するのが http://192.168.1.100:18080/plantuml のように最後に「plantuml」がついている必要がありました。
PlantUML Serverの仕様が変わったのかこのままだと動かなく自分は躓いていました。
あと、個人的にダイアグラムはsvg で表示したいので、 以前は http://192.168.1.100:18080/plantuml/svg/ のようにURLにsvg を追加していた気がしたのにexceptionだらけで表示されず、うーんとなっていました。

この辺も仕様が変わったのか特に何も追記する必要はなく、 http://192.168.1.100:18080 のみを指定します。
注意点としては、最後のスラッシュも不要です。

site_name: My Docs
theme:
  name: material

+ markdown_extensions:
+  - plantuml_markdown:
+      server: http://192.168.1.100:18080

フォーマットの指定がない場合は、デフォルトpngのようです。
自分のようにデフォルトをsvgにする場合は、方法は二通りあるようです。

• フォーマットを毎回指定する
• デフォルトのフォーマットを指定する

フォーマットを毎回指定するには以下のように「format」で指定します。

    ```plantuml format="svg"
    @startuml
    Bob -> Alice : hello
    @enduml
    ```

デフォルトで指定するにはmkdocs.yml で以下のように指定します。

site_name: My Docs
theme:
  name: material

markdown_extensions:
 - plantuml_markdown:
     server: http://192.168.1.100:18080
+    format: svg

以上で、たぶん現時点での最新のMkDocs と PlantUML を使った環境でドキュメントが作成できるかと思います。
長くなりましたが、ここまでお付き合いしていただきありがとうございました。