2026-06-069 分
Markdown と Mermaid のドキュメント
Markdown と Mermaid のドキュメント: Mermaid を含む Markdown を公開前に確認するための、貼り付け可能なデモ、レビュー項目、公開メモを含む実践ガイド。

01
このワークフローが解決すること
Markdown と Mermaid のドキュメント は、図を単なる画像ではなく保守できるドキュメントとして扱うときに役立ちます。ソースは読みやすく、プレビューはエラーを見つけやすく、エクスポートは README や wiki、ブログで使える必要があります。
対象は README、API メモ、RFC、ヘルプ記事 です。公開前に編集、プレビュー、レビューの短いループを作ることが目的です。

02
最初に貼る小さなデモ
最初から本番全体を貼らず、小さな断片で構文、ラベル、レイアウトを確認します。
最初のプレビューが動いたら、実際のサービス名、フィールド、登場人物、依存関係を追加します。
markdownCopyable demo
# Checkout flow
The API creates an order, then asks the payment service to confirm it.
```mermaid
sequenceDiagram
participant User
participant Store
participant Payment
User->>Store: POST /orders
Store->>Payment: Create payment intent
Payment-->>Store: Confirmed
Store-->>User: Order receipt
```03
プレビューで確認する点
チームメンバーが読む前提で確認します。ひとつの明確な質問に答えているか、後から安全に編集できるかを見ます。
AI 生成の場合は、名前、方向、グループ、抜けている関係を重点的に確認します。
04
よくあるミス
よくあるミスは、ひとつの図ですべてを説明しようとすることです。リクエストフロー、データ、インフラ、公開用出力に分けます。
もうひとつは画像だけを保存することです。ソーステキストを SVG や PNG と一緒に残します。
05
公開前チェックリスト
公開前に、画像の鮮明さ、長いラベル、再現できる入力例があるかを確認します。
入力、プレビュー、レビュー後の判断が見えるページほど信頼されます。