How to Embed Live Architecture Diagrams in Docs, Notion, Confluence and GitHub

Every architecture diagram that ends up as a screenshot in a wiki starts a slow countdown. The system changes, someone updates the source, and the screenshot in the onboarding guide, the runbook and the design doc stays the way it was. Six months later nobody trusts any of them.

The fix is simple to state: keep one live diagram and point every page at it. This guide covers the how, place by place: docs sites, Notion, Confluence, GitHub READMEs and chat tools, plus what to do where a page cannot show a live diagram. For the wider workflow, see Architecture diagrams that don't rot.

Three ways to show a diagram

Use the first two whenever you can, and exports only where nothing live is allowed.

Get the link and the embed code

In Archboard, open the diagram and choose Share:

1. Turn on Anyone with the link and copy the share link. Viewers watch the diagram live, without an account, and cannot edit it.
2. On Pro, turn on Embed and copy the embed code. It looks like this:

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

You can reset the link or the embed code at any time, which stops the old one from working, or turn sharing off, which disconnects viewers right away.

One thing to know before you put a live diagram on a public page: viewers see edits as they happen, along with the names and cursors of people with edit access who have the diagram open in the editor, and of AI agents working on it. Viewers' own names are never shown.

Docs sites

Plain HTML, Jekyll, MkDocs and most static site generators. Paste the embed code where the diagram should appear; their Markdown accepts raw HTML. Hugo leaves raw HTML out of Markdown by default, so put the iframe in a shortcode or set markup.goldmark.renderer.unsafe = true in the site configuration.

Docusaurus and other MDX sites. MDX expects JSX, so the style attribute must be an object and attributes use 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"
/>

Two small habits help readers: set a height that fits the diagram without scrolling, and give every iframe a title that describes the diagram, which screen readers announce.

Notion

Type /embed, choose Embed, and paste the URL from the src attribute of the embed code (not the whole iframe tag). Notion loads embeds through its own embed service; if a page cannot be shown inline, Notion displays an error instead. In that case, paste the share link as a bookmark: one click opens the live diagram.

Confluence

Confluence Cloud does not accept raw HTML or iframe code in the editor. Paste the share link, which Confluence turns into a link or card. If your organization allows Marketplace apps, an iframe or HTML macro app can show the embed inline.

Confluence Data Center has an HTML macro that administrators can enable. It lets anyone with edit access add arbitrary HTML and JavaScript to pages, so many organizations keep it off. Ask your admin before you plan around it.

GitHub READMEs and Markdown in repositories

GitHub does not render iframes in Markdown, so a live embed is not possible in a README. The best substitute is an exported SVG committed next to the code, linked to the live diagram:

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

Readers see the picture in the README, and a click opens the current version. Add "updated the diagram export?" to your pull request template, and commit the JSON export too if you want changes to the diagram reviewed as data.

Slack, Teams, Jira and email

Paste the share link. It always opens the current version, so an old message in a thread does not point at an old picture.

Practices that keep it working

• One diagram, many links. Never copy a diagram into a second file to "make a version for the wiki".
• Put the title, owner and last review date on the canvas. Embeds and links show the canvas, not your page's metadata.
• Share deliberately. A link or an embed on a public page makes the diagram public. Keep internal architecture on internal pages, and reset the link if it leaks.
• Use exports as a fallback, not a habit. Every export is a copy that can go stale.

Here is the whole setup on one canvas:

Build it in Archboard

Open any diagram, choose Share, and turn on the link; on Pro, turn on the embed too. If you are starting a diagram for your docs, the templates and examples are a quick way in, and the diagram above uses nine Core pack boxes, within the Free plan.

FAQ

Can I embed a diagram on the Free plan? Free includes the branded share link. The iframe embed is part of Pro and Enterprise.

Do viewers need an account? No. Anyone with the link or the page with the embed can view the diagram live. They cannot edit it.

Can I stop sharing later? Yes. Reset the link or the embed code to invalidate the old one, or turn sharing off to disconnect viewers immediately.

Will an exported SVG update when the diagram changes? No. Exports are copies. Re-export when the diagram changes, or use a link or embed wherever possible.

Why does my embed show an error in Notion or Confluence? Both tools control what can be embedded. Use the share link as a bookmark or card instead, or ask your admin about embed apps.

Start free — one seat, no credit card.