ライブで更新される構成図をドキュメント、Notion、Confluence、GitHub に埋め込む方法

Wiki にスクリーンショットとして貼られた構成図は、その時点からゆっくりとカウントダウンを始めます。システムが変わり、誰かが元の図を更新しても、オンボーディングガイドや Runbook、設計ドキュメントにあるスクリーンショットは元のままです。半年もすれば、どれも信用されなくなります。

解決策自体はシンプルです。ライブの図を 1 つだけ用意し、すべてのページからそれを参照させます。このガイドでは、ドキュメントサイト、Notion、Confluence、GitHub の README、チャットツールについて、場所ごとに具体的なやり方を説明し、ページがライブの図を表示できない場合の対処法も紹介します。より広いワークフローについては、腐らない構成図を参照してください。

図を見せる 3 つの方法

できる限り最初の 2 つを使い、エクスポートはライブのものを一切置けない場所に限りましょう。

リンクと埋め込みコードを取得する

Archboard で図を開き、共有を選びます。

1. リンクを知っている人をオンにして、共有リンクをコピーします。閲覧者はアカウントなしで図をライブで見られますが、編集はできません。
2. Pro では埋め込みをオンにして、埋め込みコードをコピーします。コードは次のような形です。

<iframe src="https://getarchboard.app/embed/YOUR_EMBED_TOKEN" width="100%" height="480" style="border:0;border-radius:8px;" allowfullscreen loading="lazy" title="Archboard diagram"></iframe>

リンクや埋め込みコードはいつでも再発行でき、再発行すると古いものは使えなくなります。また、共有をオフにすれば、閲覧者の接続はすぐに切れます。

ライブの図を公開ページに載せる前に、知っておくべきことが 1 つあります。閲覧者には編集がその場で見えるうえ、エディタで図を開いている編集権限のある人と、作業中の AI エージェントの名前とカーソルも表示されます。閲覧者自身の名前が表示されることはありません。

ドキュメントサイト

素の HTML、Jekyll、MkDocs、そしてほとんどの静的サイトジェネレーター。 図を表示したい場所に埋め込みコードを貼り付けます。これらの Markdown は生の HTML をそのまま受け付けます。Hugo はデフォルトで Markdown 内の生の HTML を出力しないので、iframe をショートコードに入れるか、サイト設定で markup.goldmark.renderer.unsafe = true を設定してください。

Docusaurus などの MDX サイト。 MDX は JSX を前提としているため、style 属性はオブジェクトにし、属性名は camelCase で書く必要があります。

<iframe
  src="https://getarchboard.app/embed/YOUR_EMBED_TOKEN"
  width="100%"
  height="480"
  style={{ border: 0, borderRadius: 8 }}
  allowFullScreen
  loading="lazy"
  title="Checkout service architecture"
/>

読者のためになる小さな習慣が 2 つあります。スクロールせずに図全体が収まる高さを指定すること、そしてすべての iframe に図の内容を説明する title を付けることです。title はスクリーンリーダーが読み上げます。

Notion

/embed と入力して Embed を選び、埋め込みコードの src 属性にある URL を貼り付けます（iframe タグ全体ではありません）。Notion は独自の埋め込みサービスを通して埋め込みを読み込み、ページをインラインで表示できない場合は代わりにエラーを表示します。その場合は、共有リンクをブックマークとして貼り付けてください。クリックひとつでライブの図が開きます。

Confluence

Confluence Cloud のエディタは、生の HTML や iframe のコードを受け付けません。共有リンクを貼り付けると、Confluence がリンクかカードに変換します。組織で Marketplace アプリが許可されていれば、iframe や HTML マクロのアプリを使って埋め込みをページ内に表示できます。

Confluence Data Center には、管理者が有効にできる HTML マクロがあります。編集権限を持つ人なら誰でもページに任意の HTML や JavaScript を追加できるようになるため、多くの組織では無効のままです。これを前提に計画を立てる前に、管理者に確認してください。

GitHub の README とリポジトリ内の Markdown

GitHub は Markdown 内の iframe をレンダリングしないため、README でライブの埋め込みは使えません。いちばんの代替策は、エクスポートした SVG をコードの隣にコミットし、ライブの図にリンクさせることです。

[![Checkout architecture](docs/architecture.svg)](https://getarchboard.app/s/YOUR_SHARE_TOKEN)

読者は README で図を確認でき、クリックすると最新版が開きます。プルリクエストのテンプレートに「図のエクスポートを更新しましたか？」を加えましょう。図の変更をデータとしてレビューしたい場合は、JSON エクスポートもコミットします。

Slack、Teams、Jira、メール

共有リンクを貼り付けます。リンクは常に最新版を開くので、スレッドの古いメッセージが古い図を指したままになることはありません。

うまく回し続けるための習慣

• 図は 1 つ、リンクはたくさん。 「Wiki 用のバージョンを作る」ために、図を別のファイルにコピーしないでください。
• タイトル、オーナー、最終レビュー日をキャンバスに書く。 埋め込みやリンクに表示されるのはキャンバスで、ページのメタデータではありません。
• 共有は意図して行う。 公開ページにリンクや埋め込みを置けば、その図は公開されます。社内のアーキテクチャは社内ページにとどめ、リンクが漏れたら再発行しましょう。
• エクスポートは習慣にせず、代替手段として使う。 エクスポートはどれも、古くなりうるコピーです。

ここまでの構成を 1 つのキャンバスにまとめると、次のようになります。

Archboard で設定する

任意の図を開いて共有を選び、リンクをオンにします。Pro なら埋め込みもオンにしましょう。ドキュメント用の図をこれから作るなら、テンプレートや事例から始めると手早く進められます。上の図は基本パックのボックス 9 個でできており、Free プランの範囲に収まっています。

よくある質問

Free プランで図を埋め込めますか？ Free にはブランド表示付きの共有リンクが含まれます。iframe での埋め込みは Pro と Enterprise の機能です。

閲覧者にアカウントは必要ですか？ いいえ。リンクを知っている人や、埋め込みのあるページを開いた人なら誰でも、図をライブで見られます。編集はできません。

後から共有を止められますか？ はい。リンクや埋め込みコードを再発行すれば古いものは無効になり、共有をオフにすれば閲覧者の接続はすぐに切れます。

エクスポートした SVG は、図が変わると更新されますか？ いいえ。エクスポートはコピーです。図が変わったら再エクスポートするか、できる限りリンクや埋め込みを使ってください。

Notion や Confluence で埋め込みがエラーになるのはなぜですか？ どちらのツールも、何を埋め込めるかを自分で制御しているためです。代わりに共有リンクをブックマークやカードとして使うか、埋め込み用のアプリについて管理者に相談してください。

無料で始める — 1 シート、クレジットカード不要。