はじめに
タイトルの通りですが、UML図を入れたMarkdown形式のファイルをPDFに変換する方法を記載します。
Markdownは開発者にとって非常に使いやすく、文書の記載や管理が簡単です。
しかし、顧客に提供する場合など、そのままではドキュメントとしては見づらい場合があります。
また、図を埋め込んだ場合、閲覧するためには特定のツールやプラグインが必要になり、利用者にとってのハードルが上がることがあります。
上記解決のため、MarkdownをPDFに変換することで、誰でも簡単に閲覧できるようになり非常に便利です。
環境
OS: M2 Mac
(他の環境の場合、コマンドの差分は公式サイト等で確認してください)
使うもの
- Mermaid (mermaid-cli)
- テキストで手軽に図が書くためのツールです
- PlantUML をご存知の場合、似たツールと思ってください
- Pandoc
- Markdown => PDF の変換を実現するためのツールです
- 本記事では扱いませんが、その他様々な形式に対応しています
- pandoc-ext/diagram
- Pandoc で各種ダイアグラムを変換できるようにするための拡張です
- MacTeX
- pandoc で(日本語を含む)PDFを生成するために TeX を利用します
- MacTeX は Mac向けのTeX ディストリビューションです (wiki)
手順
1. 必要ツールのインストール
Mermaid (mermaid-cli)
npm install -g @mermaid-js/mermaid-cli
Pandoc + MacTeX
brew install pandoc
brew install mactex
# パスを反映 (Terminal再起動でもOK)
eval "$(/usr/libexec/path_helper)"
pandoc-ext/diagram
GitHub から diagram.lua をダウンロードします。
curl コマンドで取得する場合は以下
curl -o diagram.lua https://raw.githubusercontent.com/pandoc-ext/diagram/refs/heads/main/_extensions/diagram/diagram.lua
2. Markdown ファイルの用意
以下のファイルを用意して、login.md という名称で保存します。
# システム設計書
## 1. はじめに
本システム設計書は、ネコネコシステムの設計をまとめたものである。
## 2. 機能一覧
- ユーザー管理機能
- ユーザー登録
- ログイン/ログアウト
- 猫管理機能
- 猫情報追加
- 猫情報編集
## 3. クラス図
```mermaid
classDiagram
class User {
+String name
+String email
+void login()
+void logout()
}
class Cat {
+String name
+float power
+void add()
+void edit()
}
User "1" -- "many" Cat : manages
```
クラス図の部分を Mermeid で記載しています。
もちろん、シーケンス図など他のダイアログも書けるので、設計書はこれでバッチリです！
VSCode で Markdown Preview Enhanced を入れると、リアルタイムでプレビューを確認できます。
https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced
3. PDF ファイルへの変換
事前に用意した diagram.lua と login.md はコマンド実行ディレクトリ内に配置している前提とします。
それ以外の場合は、適宜コマンドで指定しているパスを変更して下さい。
以下のコマンドを実行します。
pandoc ./login.md \
-o ./login.pdf \
--pdf-engine=lualatex \
-V documentclass=ltjarticle \
-V geometry:margin=20mm \
--lua-filter ./diagram.lua
| オプション | 説明 |
|---|---|
| ./login.md | 変換元のMarkdownファイル |
| -o ./login.pdf | 出力するPDFファイルの名前 |
| --pdf-engine=lualatex | PDFエンジンとしてlualatexを使用 |
| -V documentclass=ltjarticle | 日本語対応のためのドキュメントクラス設定 |
| -V geometry:margin=20mm | ページのマージン設定(お好みで) |
| --lua-filter ./diagram.lua | Mermaid 変換用のフィルターを指定 |
4. 終わり！
login.pdf というファイルが生成されます。
クラス図もしっかりと出ていますね！
最後に
簡潔ですが以上です。
GitHub Actions で自動生成する記事も別途執筆したいと思います。