技術図を編集するには、元の設計ファイルを見つけ、別のアプリケーションを開いて、別の画像をエクスポートする必要があるため、技術図が古くなってしまうことがよくあります。Mermaid は別のアプローチを採用しています。図はテキストとして定義され、ドキュメントの横に保存されます。
Mermaid を Markdown に追加するには、図の定義をフェンスで囲まれたコード ブロック内に配置します。 mermaid 言語識別子。を使用します。 Mermaid図プレビュー を使用して、ローカルで構文をレンダリングしたり、エラーを修正したり、完全な Markdown フェンスをコピーしたり、SVG をダウンロードしたりできます。
このガイドは、小さなフローチャートから始まり、シーケンス、クラス、ガント、マインド マップ、およびエンティティ関係図に向かって構築されます。
Mermaid 30秒以内
基本的な Mermaid ブロックは次のようになります。
```mermaid
flowchart LR
Draft --> Review
Review --> Publish
```
開始フェンスは、互換性のあるレンダラーにコンテンツが Mermaid 構文であることを伝えます。 flowchart LR は、左から右に配置されたフローチャートを選択します。残りの行はノードと接続を定義します。
宛先が Mermaid をサポートしていない場合、読者には通常、図の代わりにコード ブロックが表示されます。このフォールバックはソースを保持しますが、公開前に互換性をチェックすることに代わるものではありません。
テキストベースの図を使用する理由
Mermaid は、図の場合に特に役立ちます。
- はバージョン管理されたドキュメントに属します。
- はコードまたは手順に応じて変更されます。
- には意味のあるプルリクエストの差分が必要です。
- は標準の形状と関係を使用します。
- は、独自の設計ファイルがなくても編集可能である必要があります。
- は明るいテーマと暗いテーマで再生成する必要があります。
詳細なイラスト、ピクセル完璧なレイアウト、フリーハンドの注釈、または正確な手動配置を必要とするビジュアル デザインにはあまり適していません。そのような場合は、描画ツールを使用して、アクセス可能な SVG または画像をエクスポートします。
例 1: フローチャート
フローチャートは、プロセス、決定、またはルーティング ルールを記述します。
```mermaid
flowchart TD
A[Choose a DOCX file] --> B{File valid?}
B -->|Yes| C[Convert to Markdown]
B -->|No| D[Show an error]
C --> E[Review the output]
E --> F[Copy or download]
```
主要な構文:
TDは上から下へという意味です。LRは左から右を意味します。[Text]は長方形のプロセス ノードを作成します。{Text}は決定ノードを作成します。-->は、方向性のある接続を作成します。-->|Label|は接続にテキストを追加します。
次のような安定した短いノード ID を使用してください。 A or validate。表示されるラベルを括弧内に残しておくと、文言を変更してもすべての接続を変更する必要がなくなります。
サブグラフの追加
サブグラフ グループ関連の手順:
```mermaid
flowchart LR
subgraph Browser
Upload[Choose file] --> Convert[Convert locally]
end
subgraph Output
Preview[Preview Markdown] --> Save[Download file]
end
Convert --> Preview
```
グループ化によって所有権、システム境界、またはフェーズを伝達する場合は、サブグラフを使用します。装飾のためだけに箱を追加しないでください。
例 2: シーケンス図
シーケンス図は、相互作用を時間順に示します。これらは、API 呼び出し、認証、ブラウザ ワークフロー、およびイベント駆動型システムに適しています。
```mermaid
sequenceDiagram
autonumber
actor User
participant Browser
participant Converter
User->>Browser: Select DOCX file
Browser->>Converter: Pass local file data
Converter-->>Browser: Return Markdown
Browser-->>User: Show editable preview
```
一般的な矢印:
->>はしっかりとしたメッセージを送信します。-->>は破線の応答を送信します。participantはシステムまたはサービスを宣言します。actorは人間または外部の役割を宣言します。autonumberは、相互作用を順番にラベル付けします。
1 つのシナリオに焦点を当てます。すべての代替機能やすべての内部関数を示そうとするシーケンス図は、コードよりも理解しにくくなります。
代替パスを表示
```mermaid
sequenceDiagram
participant Client
participant API
Client->>API: POST /documents
alt Valid request
API-->>Client: 201 Created
else Invalid request
API-->>Client: 400 Bad Request
end
```
使用する alt, else、および end 。ブランチに数ページの説明が必要な場合は、図の下の散文へのリンクを貼ってください。
例 3: クラス図
クラス図は、型、プロパティ、操作、継承、および関係を記述します。
```mermaid
classDiagram
class Document {
+String name
+String content
+convert()
}
class MarkdownDocument {
+String frontmatter
+render()
}
Document <|-- MarkdownDocument
```
この例では、次のように述べています。 MarkdownDocument から継承 Document。クラス図は、完全なAPI リファレンス ドキュメントの自動的な置き換えとしてではなく、概念モデルとして使用します。
優れたクラス図では、読者が設計を理解するのに役立たない詳細は省略されています。すべてのプライベート フィールドを表示すると、図がソース コードの検索しにくいバージョンになってしまう可能性があります。
例 4: ガント チャート
ガント チャートは、時間の経過に伴うタスクを表示します。これらは、リリース計画、移行、およびドキュメント プロジェクトに役立ちます。
```mermaid
gantt
title Documentation migration
dateFormat YYYY-MM-DD
section Preparation
Inventory content :done, inventory, 2026-11-03, 3d
Define templates :done, templates, after inventory, 2d
section Migration
Convert documents :active, convert, 2026-11-08, 7d
Editorial review :review, after convert, 5d
section Publish
Final validation :validate, after review, 2d
```
あるタスクが別のタスクに依存する場合は、日付を明示的に保ち、タスク ID を使用します。ドキュメントに保存されている図は、実際のプロジェクトのスケジュールが変更されても更新されないことに注意してください。最新の状態に保つために所有権を割り当てます。
例 5: マインド マップ
マインド マップは、中心的なトピックを中心にアイデアを整理します。
```mermaid
mindmap
root((Markdown quality))
Structure
Headings
Lists
Tables
Accessibility
Alt text
Link text
Reading order
Publishing
GitHub
Obsidian
Documentation site
```
マインド マップは、計画中または高レベルの概要として最も効果的です。ツリー構造は実際の概念が重複する階層を暗示する可能性があるため、正確な関係にはあまり役に立ちません。
例 6: エンティティ関係図
ER 図は、データ エンティティとその関係を記述します。
```mermaid
erDiagram
AUTHOR ||--o{ DOCUMENT : writes
DOCUMENT ||--o{ REVISION : contains
DOCUMENT }o--o{ TAG : uses
AUTHOR {
string id
string name
}
DOCUMENT {
string id
string title
datetime published_at
}
```
ER 図を使用してモデルを説明し、スキーマまたは移行ファイルを使用して実装を定義します。図では、現在の説明に関係のないインデックス、制約、およびフィールドが省略されている場合があります。
公開前にプレビュー Mermaid
長い Markdown ドキュメントに図を直接記述すると、構文エラーを切り分けることが困難になります。フォーカスされたプレビュー ループは高速になります。
- 開けろ Mermaid図プレビュー.
- 外側のコード フェンスを付けずに、ダイアグラム定義のみを貼り付けます。
- 図をレンダリングします。
- 構文エラーを読み取り、参照領域を修正します。
- 生成されたフェンスされた Markdown をコピーします。
- 宛先に静的アセットが必要な場合は、SVG をダウンロードします。
- 最終的な Markdown を実際のプラットフォームでテストします。
プレビューは、厳格なセキュリティ設定を使用してブラウザに表示されます。ダイアグラムのコールバックやその他の対話型動作は、別の Mermaid インストールで許可されている場合でも無効になる場合があります。この保守的な動作は、一般的なプレビュー ツールに適しています。
一般的な Mermaid エラー
図のタイプがありません
間違っています
A --> B
正解:
flowchart LR
A --> B
最初の行は図の文法を示しています。
ラベル内の句読点により解析が中断される
複雑なラベルを引用します:
flowchart LR
A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]
これは、構文に似た括弧、句読点、およびラベルに特に役立ちます。
予約済みの Word が予期せず使用されています
Mermaid 文法にはキーワードがあります。公式フローチャートのドキュメントでは、小文字を使用することを特に警告しています。 end はフローチャートを中断する可能性があります。大文字にするか、引用符で囲まれたノード ラベル内に表示テキストを配置します。
flowchart LR
Start --> Finish["End"]
コードフェンスが正しくありません
言語識別子は、開始バッククォートの直後に属します。
```mermaid
flowchart LR
A --> B
```
周囲の Markdown 構文で必要な場合を除き、フェンス全体をインデントしないでください。
あるプラットフォームでは動作するが、別のプラットフォームでは動作しない
Mermaid は進化し、プラットフォームではさまざまなレンダラー、バージョン、セキュリティ設定、および有効な図の種類を使用できるようになります。最新のMermaid リリースでサポートされている構文機能は、別の実装または古いバージョンを使用しているプラットフォームでは失敗する可能性があります。
プラットフォーム間を移動するドキュメントには、広くサポートされている構文を優先します。必要なすべての宛先で、高度な形状、テーマ、ディレクティブ、および新しい図のタイプをテストします。
プラットフォームの互換性
互換性は、仮定するのではなくテストする必要があります。
| プラットフォーム | 現在文書化されているアプローチ | 重要な注意事項 |
|---|---|---|
| GitHub | フェンスで囲ったものを使用する mermaid block | GitHub Markdown ファイル、問題、ディスカッション、プル リクエスト、Wiki でレンダリングされるドキュメント |
| GitLab (ギットラボ) | GitLab Flavored Markdown で Mermaid コード ブロックを使用する | GitLab では、サポートされている Mermaid バージョンを文書化しています。自己管理型のインストールは異なる場合があります |
| Obsidian | フェンスで囲ったものを使用する mermaid メモ内のブロック | Obsidian のレンダラとサポートされる機能はリリース間で変更される可能性があります |
| MkDocsの材料 | Mermaid カスタム フェンスを構成する | ネイティブテーマの統合には文書化が必要です pymdownx.superfences configuration |
| 汎用 Markdown パーサー | コードのみを表示することが多い | Mermaid レンダリングには通常、JavaScript 統合またはビルド プラグインが必要です |
新しい機能に依存する前に、現在の公式ドキュメントを確認してください。
あなたが管理するドキュメント サイトの場合、Mermaid 依存関係のバージョンを固定し、アップグレードをテストします。そうしないと、構文の小さな変更によってサイト全体の図が変更される可能性があります。
Mermaid とアクセシビリティ
レンダリングされた SVG は、すべての読者にその意味を自動的に伝えるわけではありません。図を視覚的な概要として扱い、同等の説明を近くの散文で提供します。
前の変換フローチャートの場合、次のようなテキストを追加します。
ユーザーは DOCX ファイルを選択します。有効なファイルはローカルで変換され、確認のために表示されます。無効なファイルではエラーが発生します。その後、ユーザーはレビューされた Markdown をコピーまたはダウンロードできます。
アクセシビリティの実践:
- 図が説明する内容を紹介します。
- 複雑な図の後に結論を要約します。
- 色だけで意味をエンコードしない。
- 内部略語ではなく読みやすいラベルを使用します。
- 明るいテーマと暗いテーマで十分なコントラストを維持します。
- 正確なマウス操作を必要とする図は避けてください。
- は、重要な情報についてテキストまたは表の代替案を提供します。
- 静的ファイルにアクセス可能な名前を付ける必要がある場合、SVG をエクスポートするときは注意してください。
ソース コードは作成者にとっては役立ちますが、読者にとっては必ずしも優れたテキストの代替となるとは限りません。
読みやすい図の設計
図ごとに 1 つの目的を維持する
図は、「リクエストが失敗した後はどうなりますか?」などの質問に答える必要があります。または「各データ ストアを所有しているのはどのサービスですか?」システム全体を説明しようとする場合は、分割してください。
短いラベルを好む
詳細な説明を散文で記載します。ラベルが長いと、モバイル画面上でノードが狭くなり、行の折り返しが不自然になり、図が大きくなります。
意図的に方向を使用する
左から右へのフローは、短いプロセスとリクエスト パスに適しています。上から下への流れは、多くの場合、狭い画面に適しています。コミットする前に両方をプレビューします。
視覚的なスタイルを制限する
カスタム カラーは、ダーク モードまたはプラットフォーム テーマと競合する可能性があります。レンダラーのデフォルトから始めます。スタイルが意味を伝え、必要なすべてのテーマで読みやすい場合にのみスタイルを追加します。
出典をその説明の近くに置く
可能であれば、Mermaid ブロックを同じ Markdown ファイルに保存します。そのため、1 回のレビューで文章と図が一緒に変更されます。
Mermaid 対 静止画像
次の場合は Mermaid を選択してください。
- 図は頻繁に変更されます。
- ソースの差分は貴重です。
- レイアウトでは標準の図タイプが使用されます。
- 公開プラットフォームは Mermaid を確実にレンダリングします。
次の場合に SVG または PNG を選択します。
- デザインには正確な手動レイアウトが必要です。
- 宛先は Mermaid をレンダリングしません。
- 正確な外観は固定されたままでなければなりません。
- 外部共有にはスタンドアロン アセットが必要です。
便利なハイブリッドは、Mermaid ソースを維持し、それをレンダリングできない宛先に SVG をエクスポートすることです。エクスポートされたアセットの横にソースを保管し、それを再生成する方法を文書化します。
使用する Markdownから画像 、またはから SVG を直接ダウンロードします。 Mermaid図プレビュー 図自体が資産である場合。
FAQ
Mermaid は標準 Markdown の一部ですか?
No. 柵で囲まれた mermaid ブロックは、互換性のあるアプリケーションおよびビルド システムによって認識される拡張機能です。基本的なMarkdown パーサーは、これを通常のコードとしてレンダリングできます。
GitHub は Mermaid の図をレンダリングしますか?
はい。GitHub のドキュメントでは、Markdown ファイルおよびいくつかのコラボレーション サーフェスでの Mermaid のレンダリングについて説明しています。GitHub はデプロイされたレンダラーとセキュリティ設定を制御するため、新しい構文をテストします。
ObsidianでMermaidを使用できますか?
Obsidian の公式ヘルプには、Mermaid スタイルの囲み図ブロックがメモに記載されています。機能のサポートはアプリケーションのレンダラーによって変わる可能性があるため、インストールされているバージョンで複雑な図のタイプまたは新しく導入された図のタイプを確認してください。
Mermaid はアーキテクチャ文書を置き換えることができますか?
いいえ。図はシステムの 1 つのビューです。これを、決定、所有権、制約、障害動作、および権限のあるインターフェイスまたはスキーマへのリンクと組み合わせます。
ダーク モードで図のレンダリングが異なるのはなぜですか?
プラットフォームでは、異なる Mermaid テーマ、CSS 変数、フォント、背景が適用される場合があります。両方のテーマをテストするまでは、ハードコーディングされた色を避けてください。
エクスポートした SVG ファイルをコミットする必要がありますか?
パブリッシュ先で静的アセットが必要な場合、またはレンダリングされた結果が安定している必要がある場合は、SVG をコミットします。また、2 つのバージョンのドリフトを防ぐために、Mermaid ソースと文書化された再生成プロセスも保管してください。
Mermaid は機密図に対して安全ですか?
機密保持は編集者と出版ワークフローによって異なります。WordToMD のプレビューはブラウザーで図をレンダリングしますが、Markdown または SVG をリポジトリまたはサイトに公開すると、その宛先のアクセス制御に従います。
結論
Mermaid を使用すると、ソースが Markdown とともに存在するため、図の保守が容易になります。小さなフェンスで囲まれたブロックから始めて、質問に一致する図のタイプを選択し、構文をプレビューして、最終レンダラーでテストします。散文を使用して本質的な意味を説明し、宛先に静的アセットが必要な場合は SVG をエクスポートします。
の例を試してください。 Mermaid図プレビューで、周囲のドキュメントを編集します。 Markdown 編集者、将来の寄稿者がページ全体を再描画しなくても理解して更新できるように、図の焦点を絞った状態に保ちます。