Live-Architekturdiagramme in Docs, Notion, Confluence und GitHub einbetten

Jedes Architekturdiagramm, das als Screenshot in einem Wiki landet, startet einen langsamen Countdown. Das System ändert sich, jemand aktualisiert die Quelle, und der Screenshot im Onboarding-Guide, im Runbook und im Design-Doc bleibt, wie er war. Sechs Monate später traut niemand mehr auch nur einem davon.

Die Lösung ist schnell gesagt: Pflege ein einziges Live-Diagramm und lass jede Seite darauf verweisen. Dieser Guide zeigt das Wie, Ort für Ort: Docs-Seiten, Notion, Confluence, GitHub-READMEs und Chat-Tools, dazu, was du tun kannst, wenn eine Seite kein Live-Diagramm anzeigen kann. Den größeren Workflow beschreibt Architekturdiagramme, die nicht veralten.

Drei Wege, ein Diagramm zu zeigen

Nutze die ersten beiden, wo immer es geht, und Exporte nur dort, wo keine Live-Inhalte erlaubt sind.

Link und Embed-Code holen

Öffne das Diagramm in Archboard und wähle Teilen:

1. Schalte Jeder mit dem Link ein und kopiere den Freigabelink. Betrachter sehen das Diagramm live und ohne Konto, bearbeiten können sie es nicht.
2. Schalte im Pro-Plan Einbetten ein und kopiere den Embed-Code. Er sieht so aus:

<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>

Du kannst den Link oder den Embed-Code jederzeit erneuern, dann funktioniert der alte nicht mehr. Oder du schaltest die Freigabe aus, dann werden Betrachter sofort getrennt.

Eine Sache solltest du wissen, bevor du ein Live-Diagramm auf eine öffentliche Seite stellst: Betrachter sehen Änderungen in dem Moment, in dem sie passieren, und dazu die Namen und Cursor der Personen mit Bearbeitungsrecht, die das Diagramm im Editor geöffnet haben, sowie der KI-Agenten, die daran arbeiten. Die Namen der Betrachter selbst werden nie angezeigt.

Docs-Seiten

Reines HTML, Jekyll, MkDocs und die meisten statischen Site-Generatoren. Füge den Embed-Code dort ein, wo das Diagramm erscheinen soll; ihr Markdown akzeptiert rohes HTML. Hugo lässt rohes HTML in Markdown standardmäßig weg. Pack das iframe deshalb in einen Shortcode oder setz in der Site-Konfiguration markup.goldmark.renderer.unsafe = true.

Docusaurus und andere MDX-Sites. MDX erwartet JSX, deshalb muss das style-Attribut ein Objekt sein, und Attribute stehen in 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"
/>

Zwei kleine Gewohnheiten helfen deinen Lesern: Wähle eine Höhe, in die das Diagramm ohne Scrollen passt, und gib jedem iframe einen title, der das Diagramm beschreibt. Screenreader lesen ihn vor.

Notion

Tippe /embed, wähle Embed und füge die URL aus dem src-Attribut des Embed-Codes ein (nicht das ganze iframe-Tag). Notion lädt Einbettungen über einen eigenen Embed-Dienst; kann eine Seite nicht inline angezeigt werden, zeigt Notion stattdessen einen Fehler. Füge in diesem Fall den Freigabelink als Lesezeichen ein: Ein Klick öffnet das Live-Diagramm.

Confluence

Confluence Cloud akzeptiert im Editor weder rohes HTML noch iframe-Code. Füge den Freigabelink ein; Confluence macht daraus einen Link oder eine Karte. Wenn deine Organisation Marketplace-Apps erlaubt, kann eine iframe- oder HTML-Makro-App die Einbettung direkt auf der Seite anzeigen.

Confluence Data Center hat ein HTML-Makro, das Administratoren aktivieren können. Damit kann jeder mit Bearbeitungsrecht beliebiges HTML und JavaScript in Seiten einfügen, deshalb lassen viele Organisationen es ausgeschaltet. Frag deinen Admin, bevor du damit planst.

GitHub-READMEs und Markdown in Repositories

GitHub rendert keine iframes in Markdown, eine Live-Einbettung ist in einem README also nicht möglich. Der beste Ersatz ist ein exportiertes SVG, das neben dem Code committet ist und auf das Live-Diagramm verlinkt:

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

Leser sehen das Bild im README, und ein Klick öffnet die aktuelle Version. Nimm „Diagramm-Export aktualisiert?“ in dein Pull-Request-Template auf und committe auch den JSON-Export, wenn Änderungen am Diagramm als Daten reviewt werden sollen.

Slack, Teams, Jira und E-Mail

Füge den Freigabelink ein. Er öffnet immer die aktuelle Version, also verweist eine alte Nachricht in einem Thread nicht auf ein altes Bild.

Praktiken, die das Ganze am Laufen halten

• Ein Diagramm, viele Links. Kopiere ein Diagramm nie in eine zweite Datei, um „eine Version fürs Wiki zu machen“.
• Schreib Titel, Owner und das Datum des letzten Reviews auf den Canvas. Einbettungen und Links zeigen den Canvas, nicht die Metadaten deiner Seite.
• Teile bewusst. Ein Link oder eine Einbettung auf einer öffentlichen Seite macht das Diagramm öffentlich. Halte interne Architektur auf internen Seiten und erneuere den Link, wenn er nach außen gelangt.
• Nutze Exporte als Notlösung, nicht aus Gewohnheit. Jeder Export ist eine Kopie, die veralten kann.

Hier ist das ganze Setup auf einem Canvas:

In Archboard umsetzen

Öffne ein beliebiges Diagramm, wähle Teilen und schalte den Link ein; mit Pro schaltest du auch die Einbettung ein. Wenn du ein Diagramm für deine Docs neu anlegst, sind die Vorlagen und Beispiele ein schneller Einstieg. Das Diagramm oben besteht aus neun Kästen des Basis-Packs und passt damit in den Free-Plan.

FAQ

Kann ich ein Diagramm im Free-Plan einbetten? Free enthält den Freigabelink mit Branding. Die iframe-Einbettung gehört zu Pro und Enterprise.

Brauchen Betrachter ein Konto? Nein. Alle, die den Link haben oder die Seite mit der Einbettung öffnen, können das Diagramm live ansehen. Bearbeiten können sie es nicht.

Kann ich das Teilen später beenden? Ja. Erneuere den Link oder den Embed-Code, um den alten ungültig zu machen, oder schalte die Freigabe aus, um Betrachter sofort zu trennen.

Aktualisiert sich ein exportiertes SVG, wenn sich das Diagramm ändert? Nein. Exporte sind Kopien. Exportiere neu, wenn sich das Diagramm ändert, oder nutze, wo immer möglich, einen Link oder eine Einbettung.

Warum zeigt meine Einbettung in Notion oder Confluence einen Fehler? Beide Tools bestimmen selbst, was eingebettet werden darf. Nutze stattdessen den Freigabelink als Lesezeichen oder Karte, oder frag deinen Admin nach Embed-Apps.

Kostenlos starten — ein Seat, keine Kreditkarte.