複雑なフローチャートやシーケンスタイムラインなどの特定のアーキテクチャレイアウトに取り組む前に、図の構造を制御する基盤となるルールを理解することが不可欠です。MermaidのマニュアルMermaidは、明快で非常に直感的なテキスト表記システムに依存しています。エンジンがキャンバスタイプを初期化し、構造的要素に名前を付け、方向性の矢印をルーティングする方法を理解すれば、どんな複雑なシステムレイアウトもまったく自然に書けるようになります。
この簡単な導入では、VPasCodeワークスペース内のほぼすべてのMermaid図タイプに適用される、グローバルな構造的構文メカニズムをカバーしています。
1. 必須の図タイプラッパー
Mermaidコードのすべてのブロックは、最初の行で明示的にその図のアーキタイプを宣言しなければなりません。これにより、VPasCodeパーサーはプレビューキャンバスでどの構造的エンジンを起動すべきかを正確に把握できます。
graph TD— 上から下へ配置されたフローチャートレイアウトを指定します。sequenceDiagram— 時系列的な実行タイムラインチャートを指定します。classDiagram— 構造的なオブジェクト指向ソフトウェアのブループリントを指定します。
他のテキストから図に変換するエンジンとは異なり、Mermaidは終了タグを必要としません。パーサーは1行目の構造的宣言を読み取り、コードブロックコンテナ内に直接含まれるすべての内容をコンパイルするだけです。
2. 要素の宣言：IDと表示ラベル
ソフトウェアシステムをモデル化する際、コンポーネント、データベース、マイクロサービスなどのさまざまな構造的要素を作成します。Mermaidでは、短い内部のアルファベット・数字IDを定義し、直ちに視覚的形状を制御する括弧スタイルを記述し、ユーザー向けの表示名を指定することで要素を宣言します：
microservice_id[支払い処理API]
db_id[(ユーザー取引SQL)]なぜこれがベストプラクティスなのか： 短く明快な内部ID（例：microservice_id）を使用すると、後で関係線を描く際にずっと速くなります。もし「支払い処理API」から「グローバル決済サービス」に顧客向けラベルを変更する必要が生じた場合、その宣言が行われている1行だけを編集すればよく、スクリプト全体で数十行を更新する必要はありません。
3. 関係性の矢印と方向ルーティングの習得
システムノード間の接続は、ダッシュ（-）、イコール記号（=）、矢印の括弧（>）の組み合わせで描かれます。線のスタイルにより、自動レイアウトエンジンが図をどのようにスケーリングするかを暗黙的に制御できます：
A --> B要素Aから要素Bへと直線的に向かう標準の方向性のある矢印を描きます。A --- B矢印の先端のない平らで方向性のないリンク線を描き、シンプルな関連付けに最適です。A -.-> B点線の依存関係線を作成し、非同期の依存関係やネットワークのWebhookを示す業界標準です。A ==> B太く太字の接続線を作成し、主要なデータ処理経路や重要なインフラ構成のリンクを強調するのに最適です。
4. インラインでの文脈の追加：ラベルとコードコメント
明確なドキュメント作成は、視覚的な線やテキストスクリプトの周囲に適切な文脈を配置することに大きく依存します：
接続線へのラベル付け
接続線の間にテキスト文字列を挿入するか、関係性のマッピングの直後にパイプ文字（”|Text|”）を追加することで、説明文を接続線に直接追加できます：|Text|) 関係性のマッピングの直後に：
client_id -- "HTTPS POST /v1/checkout" --> api_id
client_id --> |HTTPS POST /v1/checkout| api_idコードコメントの記述
スクリプトファイル内に管理上のメモ、デザインのクレジット、またはアーキテクチャの説明を視覚的なボックスをキャンバス上に描画せずに残したい場合は、ダブルパーセント記号（”%%”）を使用してください。これによりエンジンはその行を完全に解析しないように指示されます：%%) これによりエンジンはその行を完全に解析しないように指示されます：
%% TODO: DevOps移行が完了したら、この境界ボックスを更新する必要がある
[レガシーモノリス] --> [新しいマイクロサービス]