はじめに
設計資料のシーケンス図やER図、どうやって管理していますか？作図ツールで描いた画像は、仕様が変わるたびに開き直して修正して書き出して……と手間がかかりますし、Gitで差分を追うこともできません。
そこで人気なのが「テキストから図を生成する」アプローチです。Mermaidを使っている方も多いと思いますが、今回ご紹介する**Pintora（ピントラ）**は、MermaidとPlantUMLの両方に影響を受けつつ、ブラウザとNode.jsのどちらでも同じように動くことを重視して設計されたライブラリです。
「Mermaidで十分では？」と思った方にこそ、Pintoraならではの魅力をお伝えしたいと思います。
Pintoraとは
Pintora（スペイン語で「女性画家」の意味）は、テキスト記述からダイアグラムを生成するJavaScript製のライブラリです。ブラウザではSVGまたはCanvasに描画でき、Node.js環境ではPNG/JPG/SVGファイルとして出力できます。GitHubでは1.3k以上のスターを獲得しており、TypeScriptで書かれています。
主な特徴
- ブラウザとNode.jsの両対応 - 同じ記法・同じコアで、Webページへの埋め込みもCLIでの画像生成もできます
- グローバルを汚さない自己完結設計 - ページ全体のスタイルに影響を与えないため、既存サイトへ安心して組み込めます
- プラグインによる拡張性 - 独自のダイアグラム定義を作成して配布できる拡張システムを備えています
- 豊富なダイアグラム - シーケンス図、ER図、コンポーネント図、アクティビティ図、クラス図に加え、マインドマップ・ガントチャート・DOT図（実験的機能）に対応しています
構文はMermaidやPlantUMLに近いので、これらの経験があればほとんど学習コストなしで移行できます。VSCode拡張「pintora-vscode」やブラウザ上で試せるライブエディタも公式に用意されています。
インストール
ブラウザで使う場合
npmでインストールする場合は、standaloneパッケージを追加します。
npm install @pintora/standalone
CDN経由なら、scriptタグを1つ追加するだけで使えます。
<script src="https://cdn.jsdelivr.net/npm/@pintora/standalone/lib/pintora-standalone.umd.js"></script>
CLIで使う場合
コマンドラインから画像を生成したい場合は、CLIパッケージをグローバルインストールします。
npm i -g @pintora/cli
基本的な使い方
ページ内のコードブロックを図に変換する
もっとも手軽なのは、preタグに書いたダイアグラム記述を自動レンダリングする方法です。
<pre class="pintora">
mindmap
* 技術ブログ
** ネタ探し
** 執筆
** 公開
</pre>
<script type="module">
import pintora from 'https://cdn.skypack.dev/@pintora/standalone'
document.querySelectorAll('.pintora').forEach((codeElement) => {
pintora.renderContentOf(codeElement)
})
</script>
これだけで、preタグの中身がマインドマップのSVGに置き換わります。UMDビルドを使う場合は pintora.default.initBrowser() を呼び出す形になります。
renderTo APIで描画先を制御する
アプリケーションに組み込む場合は、renderTo APIで描画先やテーマを細かく指定できます。
import pintora from '@pintora/standalone'
const code = `
sequenceDiagram
participant User
participant System
User->>System: リクエスト送信
activate System
System-->>User: レスポンス返却
deactivate System
`
const container = document.createElement('div')
document.body.appendChild(container)
pintora.renderTo(code, {
container,
renderer: 'svg', // 'svg' または 'canvas'
config: {
themeConfig: {
theme: 'dark',
},
},
})
onRender や onError といったコールバックも用意されているので、レンダリング完了後の処理やエラーハンドリングも組み込みやすくなっています。
CLIで画像ファイルを生成する
Node.js側の強みが活きるのがCLIです。ダイアグラム記述を書いたテキストファイルを用意して、コマンド1つで画像化できます。
# sequence.pintora をPNGに変換
pintora render -i sequence.pintora -o sequence.png
# 背景色を指定してJPGに変換
pintora render -i sequence.pintora -b "#FAFAFA" -o sequence.jpg
# ダークテーマ・幅1000pxで出力
pintora render -i sequence.pintora --theme dark --width 1000 -o sequence.jpg
ドキュメント生成パイプラインやCIに組み込めば、テキストの更新だけで図が自動的に再生成される仕組みが作れます。
実践的なユースケース
シーケンス図で認証フローをドキュメント化する
Pintoraのシーケンス図はMermaid互換の構文をベースに、独自の拡張が加えられています。たとえば == 区切り == による区切り線や、@start_note による複数行ノートが使えます。
sequenceDiagram
participant Browser as [<actor> ブラウザ]
participant API
participant DB as [<database> DB]
== ログイン ==
Browser->>API: POST /login
activate API
API->>DB: ユーザー照会
DB-->>API: ユーザー情報
API-->>Browser: セッショントークン
deactivate API
@start_note right of API
トークンの有効期限は24時間。
失効後は再ログインが必要です。
@end_note
[<actor> 名前] や [<database> 名前] のように参加者のシンボルを変えられるのはPintoraならではで、PlantUMLに慣れた方には嬉しいポイントです。
ER図でテーブル設計を共有する
データベース設計のレビューにはER図が便利です。
erDiagram
USER ||--o{ POST : writes
POST ||--o{ COMMENT : has
USER {
int id PK
string name
string email
}
POST {
int id PK
int user_id FK
string title
}
このテキストをリポジトリに含めておけば、テーブル定義の変更がプルリクエストの差分としてそのままレビューできます。
CIでドキュメント画像を自動生成する
@pintora/cliをCIに組み込むと、「テキストを直せば図も更新される」運用が完成します。npm scriptsに登録しておくと便利です。
{
"scripts": {
"diagrams": "pintora render -i docs/architecture.pintora -o docs/images/architecture.png"
}
}
ブラウザ用のヘッドレス環境を必要とせずNode.jsだけで画像を生成できるため、CI環境がシンプルに保てるのは大きな利点です。
まとめ
Pintoraは、MermaidとPlantUMLの良いところを取り込みながら、ブラウザとNode.jsの両方でシームレスに動くことを追求したダイアグラム生成ライブラリです。
- テキストから8種類のダイアグラムを生成できます
- ブラウザではSVG/Canvas、Node.jsではPNG/JPG/SVGを出力できます
- CLIが公式提供されており、CIでの画像自動生成が簡単です
- プラグインシステムで独自ダイアグラムの追加もできます
まずは公式のライブエディタで構文を試してみて、手応えを感じたらCLIをドキュメント運用に組み込んでみてください。「図のメンテナンスが億劫」という悩みから、きっと解放されるはずです。