Using PlantUML in Markdown within VSCode

mitsuruk

2024年11月28日 21:11

0. 色々と追加・修正しました

`9`が二つあったので、ちゃんと連番に修正
「8. 色々と表示して動作確認」に参考になるサイトを追加
「11.正規表現をUMLで」を追加
「12.ワークスペースを使う時の注意点」を追加
plantuml.jarのファイル名の扱いを変更
VSCodeでワークススペースを使っている場合の注意点を追加

1. Goal

MacOS上でVSCodeを使ってPlantUMLを markdownファイルの中に埋め込みたい
専用の拡張子を持つファイルにPlantUMLを使って記述するのは割と簡単なのですが、拡張子 .md のファイルに埋め込みたいのです

PlantUMLを生成する際に、ローカルにインストールされた plantuml.jarを直接呼び出してサーバーを使わずに環境構築をしたい

2. Markdownである必要性

主に数式を埋め込みたいのでLatexのサポートは必須
mermaid, Graphvizなどを使って記述したドキュメントが多いので、PlantUMLも混在させたいという理由
PlantUMLにpngやSVGを生成させてmarkdownにlinkする方式は使いたくなかった

3. 私の環境

MacOS 15.1.1（24B91）
VSCode Version: 1.95.3

brew install graphviz

~ $ brew info graphviz     
==> graphviz: stable 12.2.0 (bottled), HEAD
Graph visualization software from AT&T and Bell Labs
https://graphviz.org/
Installed
/opt/homebrew/Cellar/graphviz/12.2.0 (281 files, 7.8MB) *
  Poured from bottle using the formulae.brew.sh API on 2024-11-04 at 16:26:25
From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/g/graphviz.rb
License: EPL-1.0

java環境

~ $ which java
/usr/bin/java

~ $ java -version
openjdk version "21.0.4" 2024-07-16 LTS
OpenJDK Runtime Environment Temurin-21.0.4+7 (build 21.0.4+7-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.4+7 (build 21.0.4+7-LTS, mixed mode)
~ $

インストールされていない場合は、Oracle JDKやOpenJDKをインストールしてください。
本来ならjavaはインストールしたくないのですが仕方ない

plantuml.jarのダウンロードとインストール
以下から最新のplantuml.xxxxxx.jarをダウンロードする

https://plantuml.com/ja/download
https://github.com/plantuml/plantuml/releases/tag/v1.2024.8

ダウンロードしたjarファイルは任意の場所で良いがフルパス名をメモしておくこと
私は VSCodeのsettings.jsonと同じディレクトリである .vscodeに格納した

4. VSCode プラグイン

Markdown Preview Enhanced インストールね
Graphviz Markdown Preview まぁインストールした方が良いと思う

上記のプラグインを入れます
Markdown Preview Enhancedは高速なのでお勧めします
mermaid, graphviz用のpreviewがインストールされた場合、disableにしてから描画に問題なければMarkdown Preview Enhancedに乗り換えて、他のpreviewは削除しても良いと思う
もちろん、disableにしておいてキープしても問題ない

5. settings.jsonに情報を追加

    ,

    "plantuml.java": "java",
    "plantuml.jar": "/パス名/.vscode/plantuml-1.2024.8.jar",
    "plantuml.commandArgs": [
        "-DPLANTUML_LIMIT_SIZE=8192"
    ],
    "plantuml.exportFormat": "png",
    "plantuml.previewAutoUpdate": true,

    // markdown-preview-enhancedの設定を追加
    "markdown-preview-enhanced.plantumlJarPath": "/パス名/.vscode/plantuml-1.2024.8.jar",
    "markdown-preview-enhanced.enableScriptExecution": true
}

追記するブロックの前の ","を忘れないように記述して下さい
私は忘れて時間をロスしました
最後の"}"は、不要です(判ってください)

"/パス名/.vscode/plantuml-1.2024.8.jar"

これは、パス名を .vscodeのディレクトリがあるディレクトリ名に読み替えて下さい
2カ所ありますので忘れないように
当然、plantuml-1.2024.8.jarは、plantuml.jarにリネームして問題ありません
~~私は現状のバージョンが判るようにこのような書き方(ダウンロードしたファイル名そのまま)を採用しています~~
`11.ワークスペースを使う時の注意点`を参照してください

6. なぜかVSCodeを再起動

理由はわかりませんが、再起動した方がベターの模様です

7. テストコード

ファイル名は、basic.md です。
ファイル名はどうでも良いですが、拡張子 .md が重要です

```plantuml
' @startuml
Alice -> Bob: Hello ボブ!
Bob --> Alice: Hi ありす!
' @enduml
```

プレビューを出すには上記の左ペインの上部にある□二つに虫眼鏡?がついたアイコンをクリックします

8. 色々と表示して動作確認

http://real-world-plantuml.com

ここは面白いなぁ
色々なサンプルがある
気になるサンプルをクリックしてコードを表示してコピー&ペースト

注意点

@startuml と@endumlはコメントアウトしないとエラーとなる事が多い
私は面倒なので、すべてコメントアウトしています
なぜか、上のサンプルコードではコメントアウトしなくても表示されます
ちょっと長いとエラーとなるのですが、追求はしていないです

一目でわかるPlantUML
https://plantuml.com/ja-dark/

すごくわかりやすい実例が豊富
かなりの力作サイトと思います
ここで望むものに近いものを探すのが一番良いアプローチかもしれない

9. 日本語のPlantUML のドキュメント

ドキュメント（英語）と見比べて気がついたけど、ちょっとバージョンが古いのかな？

https://pdf.plantuml.net/PlantUML_Language_Reference_Guide_ja.pdf

10. 色々と混在して表示させてみる

```plantuml
' @startuml
Alice -> Bob: Hello ボブ!
Bob --> Alice: Hi ありす!
' @enduml
```

ここは、Latex(Katex)
$$\parallel x\parallel =\sqrt{x_{1}^{2}+x_{2}^{2}+\cdots +x_{n}^{2}} = \sum_{i=1}^{n} a_{i}^{2}$$

ここは、mermaid
```mermaid
%%{init: {"pie": {"textPosition": 0.5}, "themeVariables": {"pieOuterStrokeWidth": "5px"}} }%%
pie showData
    title Key elements in Product X
    "Calciumカルシウムかるしうむ👻" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5


```

ここは、Graphviz
```Graphviz
digraph G {
        node [shape=circle];
    A -> B -> C;
    B -> D;
    C -> D;
}
```

Enjoy !!

https://plantuml.com/ja-dark/regex

11.正規表現をUMLで

一目でわかるPlantUML
https://plantuml.com/ja-dark/
このサイト見てみると正規表現をUMLで表示する例が載っている
ドキュメントとしては、https://plantuml.com/ja/regex
英語ですけどね

で、正規表現で年月日日時のサンプルを書いてみた

```plantuml
@startregex
title 正規表現のテスト \n "yyyy/mm/dd HH:MM:SS" \n [0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])\s+([0-1]?[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]\b
[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])\s+([0-1]?[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]\b
@endregex
```

当然のことながら私の意図した通りになっている
オートマトンの教科書とか読むと正規表現について色々と書いてあるのが多い
正規表現は有限オートマトンに変換可能（記述能力に関して等価とも表現される）なので目で見て確認できるのは楽しいし勉強になる（ならない人もいるけどさ）

12.ワークスペースを使う時の注意点

plantuml.jarのファイル名の扱いの記述を最初の掲載時と変更しました
jarファイルのファイル名は、plantuml-1.2024.8.jarのように年・月が含まれている形式になっています
滅多にバージョンを上げる必要はないとは思うのですが、日本人って（私も）自分用に使う時は最新バージョンが好きですよね（勝手に思っている）

ふと見るとバージョンが上がっていました・・・
plantuml-1.2025.0.jar
特に理由はないけどバージョンアップしたい・・・・

やってみた
セットアップの時に触ったファイルはsettings.jsonだけのはず
古いjarをリネームしてから新しいファイルを導入してsettings.jsonを変更
動かない・・・
なぜか古いバージョンのjarが無いと言ってくる
誰がどの設定を見ているのだろうか
で、VSCodeのディレクトリを検索
なんと、Workspaceの設定ファイルに記述がありました
設定ファイルにコピーされている・・・

以下が新しい手順

jarファイルのレイアウトを変更
使用するjarファイルはそのままのファイル名で .vscodeディレクトリに格納
macOSなので、ln コマンドで同じディレクトリにリンクを作成
作成するリンクはplantuml.jar

簡単に言えば、持ってきたjarファイルはそのままで、参照するのはリンクしたファイル
こんな感じ

.vscode $ ln -snf plantuml-1.2025.0.jar plantuml.jar
.vscode $ ls -l plantuml*                           
-rw-r--r--@ 1 mik  staff  21680166  2  5 20:17 plantuml-1.2025.0.jar
lrwxr-xr-x  1 mik  staff        21  3  7 23:32 plantuml.jar -> plantuml-1.2025.0.jar
.vscode $

ln -snf plantuml-1.2025.0.jar plantuml.jar
これは、plantuml.jarというリンク先が存在しても上書きして新しいリンクを作成するというコマンドオプションを使っている

Windows 10にはシンボリックリンクを作成するのためのmklinkというコマンドがあるそうですが、Windwosはよく知らないので・・・

settings.jsonの中のファイル名をリンクとして生成したファイル名に記述変更する事を忘れずに

ワークスペースの記述も変更
ワークスペース機能を使用すると
<ワークスペース名>.code-workspaceというファイルが作成される

すでに存在するなら変更する必要がある
このファイルの中にjarファイルの位置が記述されている（たぶん1ヶ所)
ここをリンクとして作成したplantuml.jar を指すように変更