Zenn
🐙

VSCodeでMarkDownとPlantUMLを使う

2024/04/27に公開
VS Code
PlantUML
tech

MarkDownの中に、PlantUMLで作成した図を挿入する方法を紹介します。

PlantUMLとは

PlantUMLは、UML作成ツールの一種で、テキストベースのシンタックスでUML図を記述することができます。
多くのUML図の種類をサポートしており、UML図を簡単かつ迅速に作成することができます。
Javaで開発されたオープンソースのツールであり、GPLv3ライセンスで配布されています。
テキストベースなので非常に軽量です。
astahの有料化に伴ってPlantUMLを使い始めた人も多いと思います。
astahと違って、コードベースで書く必要があるので、最初は戸惑うかもしれません。

PlantUMLの良い点

バージョン管理に向いている

テキストベースのため、マージ・差分の比較が簡単に行えます。
SVN/Gitといったバージョン管理のソフトでの履歴管理もテキストベースのため、
履歴管理と変更点の確認が容易に行なえます。
Excelなどのバイナリベースのだと、単純な比較ツールでは変更点の確認ができません。
PlantUMLはテキストベースのため簡単に把握できます。
コードと設計書の管理が容易になります。

無料

astahの無料版がなくなったことで難民となった人の受け皿になっています。
急に有料化なることも気にせずに使用することができます。

描画が簡単

astahでシーケンスを書く場合に、ライフラインの位置など、意図したところに線がかけないことがあります。
PlantUMLの場合、線の場所を明示的に書くことができます。
レイアウトも自動でやってくれるので、位置の調整をする必要がありません。

@startuml

A -> A: Method1
activate A

A -> A: Method2
activate A

A -> B: MethodAB
activate B

B -> C: MethodBC
activate C
C --> B: return
deactivate C

B --> A: return
deactivate B
deactivate A
deactivate A

@enduml

ファイルサイズが小さい

テキストベースのため、ファイルサイズが小さいです。
テキストエディタで編集できるため、起動も早いです。

PlantUMLの悪い点

描画がしにくい

良い点の反対となってしまいますが、astahのようなGUIで書けるソフトは、とても直感的に使用できます。
単純な線に線をつなげるだけなら、astahの方が簡単に書ける場合があります。
描画に関しては、一長一短があります。

PlantUML+VScodeがおすすめの理由

設計書に落とし込む前に、考えをまとめるため、Markdownの中にPlantUMLを使っています。
VSCodeとPlantUMLが使いやすいです。

PlantUMLをMarkDownの中に書くことができる

設計書に落とし込む前の考えをまとめるために、Markdownの中にPlantUMLを使っています。
設計書として書くなら、コメントも挿入できるので、PlantUMLのみで書く方がいいですが、設計書に落とし込む前の考えをまとめるために、Markdownの中にPlantUMLを使っています。
MarkDown内で内容をまとめつつ、簡単なシーケンスであったり、MindMapを書くために、PlantUMLをMarkDownの中に使っています。

MarkDownで使用するときは、「plantuml」から「」の中にPlantUMLの記述を書くことができます。

@startuml
Class1 <|-- Class2
@enduml

MarkDownに別ファイルのplantumlのファイルをインクルードすることが可能です。

「!include」の後のファイル名にインクルードしたいファイル名を書くとUMLが表示されます。

!include test.pu

エディタとして優秀

PlantUMLで使う構文を入力補助で、候補を上げてくれるので、非常に便利です。
MarkDownで文章が書きやすいです。

MacとWidnowsの両方に対応

OSに依存せずに同じ使い方ができます。
Excelなどでは、OSの違いによって、使い勝手がわかることがありますが、VsCodeは全く同じ使い方ができます。

インストール方法

PlantUMLのインストール方法

今回はMacOSのインストール方法を紹介します。
ここでインストールするのは以下のソフトです。

インストールするソフト

  • graphviz
    OSSのグラフ描画ツールです。PlantUMLはこのツールによって描画されます。
  • Java

Homebrewを使用して、以下のコマンドでインストールします。

brew install graphviz adoptopenjdk

adoptopenjdk：簡単に言うとJavaのことです。

PlantUMLをVSCodeにインストール

以下のプラグインをインストールします。

  • PlantUML
    PlantUMLを扱えるようにするプラグインです。
  • Markdown Preview Enhanced
    MarkDown上でPlantUMLを描画できるようにするViewです。

プラグインのインストール方法は簡単です。
プラグインから検索するして、「Install」をクリックするだけです。

Markdown Preview Enhancedの設定

Markdown Preview Enhancedがplantuml.jarを参照できるように設定する必要があります。

plantuml.jarの場所

plantuml.jarはVSCodeの拡張がインストールされているフォルダに入っています。

/Users/xx(UserName)/.vscode/extensions/jebbs.plantuml-2.17.5/plantuml.jar

Markdown Preview Enhancedの設定

「Extension Settings」を選択します。

"markdown-preview-enhanced.plantumlJarPath"にplantuml.jarのパスを設定します。

トラブルシュート

「Error found in diagram test ...」

「Error found in diagram test ...」というエラーが出たることがあります。
これはフリーフォントの"Times"がないことを示すエラーです。
フォントをインストールすれば、解決します。

フォントをダウンロード

こちらのサイトからフォントをダウンロードしてください。

フォントをインストール

フォントのインストールはAppleの公式を参考に実施します。
「＋」を押します。

ダウンロードしたファイルを選択すれば完了です。
これでエラーが出なくなります。

Discussion