Docs & Code Guide

Embed a diagram in Confluence: the iframe macro first, image by URL with a caveat

Confluence pages outlive the architectures drawn on them, which is exactly the problem. Confluence Cloud gives you two routes to a diagram that follows its source instead of freezing at paste time: the iframe macro, which is dependable, and inserting an image by link, which comes with a behavior you need to know about before trusting it. Here are both, plus a straight answer on when Draw.io is the better tool.

Try it free
7 min readFor teams whose architecture pages live in Confluence

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

180/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

The iframe macro is the reliable live route

Confluence Cloud ships a native Iframe macro: type /iframe in the editor, paste a URL, set width and height, done. The macro renders the external page inside the Confluence page on every view, so nothing is copied and nothing freezes. Point it at an interactive diagram page and readers pan and zoom the current diagram without leaving Confluence.

A Datadef project shared public has a page built for exactly this: chrome-less, pan and zoom, a small attribution linking to the full diagram. One failure mode to know: a site that forbids framing with X-Frame-Options or a frame-ancestors policy leaves the macro empty. The Datadef embed page allows framing, so it renders.

In the editor, type /iframe and paste:
https://datadef.io/embed/my-platform-a1b2c3d4

Suggested size: width 100%, height 600.

If you need a plain image instead (see the caveat below):
https://datadef.io/api/embed/my-platform-a1b2c3d4

Why the HTML macro is not the answer

Confluence administrators can enable an HTML macro that renders arbitrary markup, and security teams disable it for good reasons: arbitrary HTML in a wiki is an XSS surface. On most Cloud sites it is unavailable, and asking an admin to enable it for a diagram is the wrong trade when the sanctioned Iframe macro does the job.

If your site restricts even the Iframe macro, the fallback order is: image by URL with the attachment check above, then a linked thumbnail that opens the live diagram in a new tab.

Draw.io in Confluence, honestly

The Draw.io macro is the most mature diagramming integration Confluence has: diagrams live as attachments on the page, open in an editor without leaving Confluence, and version alongside the page. If the Confluence page is itself the source of truth for the diagram, Draw.io is a genuinely strong choice and pretending otherwise would be silly.

The trade appears when the truth lives in the repository, not on the page. A Draw.io diagram is updated by a person redrawing it; nothing connects it to the system it depicts. An embedded diagram whose source can be regenerated from the codebase by an AI agent closes that loop: the Confluence page shows whatever the diagram currently is, and the diagram follows the code. Which model fits depends on where your team wants the truth to live, and wiki rot is what happens when that question goes unanswered.

Keeping the page true after the architecture changes

The embed removes the re-paste step. The diagram edit remains, and it can be manual, edit in Datadef and every Confluence page showing it follows, or delegated: the Datadef MCP server (registry name io.datadef/mcp) lets a connected agent like Claude Code update the diagram from what it reads in the repository, after a merge, on a schedule, or on request during review. Datadef does not watch repositories and nothing regenerates by itself; the loop is one agent call or CI command away. Connecting one requires an API key, available with a paid plan.

The visibility limit applies here as everywhere: the embed URLs exist only while the project is shared public, and a private project turns them into 404s. Confluence spaces full of confidential architecture may be better served by Draw.io or by periodic exports, staleness accepted. The broader practice is in keep your internal wiki in sync.

Rule of thumb

Iframe macro for live diagrams readers study. Image by URL only after confirming Confluence did not copy it into attachments. Draw.io when the Confluence page itself is the source of truth.

FAQ

How do I embed a live diagram in Confluence?

Type /iframe in the Confluence Cloud editor and paste the diagram embed URL, for example https://datadef.io/embed/your-slug, then set width and height. The iframe macro renders the external page on every view, so the diagram on the page always matches the source.

Why did my linked image in Confluence stop updating?

When you insert media by link, Confluence tries to copy the file and attach it to the page so content does not change under readers. If it succeeded, your page shows a frozen snapshot. Check the page attachments: if the image is there, delete it and use the iframe macro instead, or re-insert and confirm it stayed an external reference.

Why is the iframe macro showing an empty box?

The usual cause is the framed site refusing to render inside iframes via X-Frame-Options or a frame-ancestors policy, which Confluence cannot override. Test the URL in a normal browser tab; if it loads there but not in the macro, the site blocks framing and you need an image URL or a different source.

Should I use Draw.io or an embedded diagram in Confluence?

Use Draw.io when the Confluence page is the source of truth: it is mature, edits in place, and versions with the page. Use a live embed when the truth is the codebase and the diagram should follow it, especially if an AI agent regenerates the diagram from the repository after changes.

Can I embed a private diagram in Confluence?

Not as a live embed. The embed URLs exist only for projects shared public; making the project private turns both the iframe page and the image URL into 404s. For confidential architectures, use Draw.io or upload a static export, accepting that it no longer follows the source.