How to Embed a Diagram in Confluence

Confluence is the default wiki for a great many teams, holding architecture docs, runbooks, process descriptions, and project spaces that are all clearer with diagrams. But a diagram in Confluence can be one of two very different things: a static image frozen at the moment it was added, or a live embed that stays connected to its source and updates as the source changes. Which one you choose determines whether the diagram remains a reliable part of the wiki or becomes one more stale artifact that readers trust to their cost.

This guide covers both approaches, their trade-offs, and how to keep an embedded diagram accurate across a shared team wiki where many people read and few maintain. The reference tool is Atlas Diagram Studio at /diagrams, which lets you build a diagram once and either embed it live or export it as PNG, SVG, or PDF for a static placement, with PPTX, JSON, Mermaid, and .drawio also available. The live-versus-static distinction is identical to the one in Notion and every other docs tool, so getting it right in Confluence is the same discipline applied to a different wiki.

Live embed versus static image

The static option is to export the diagram as an image and attach or paste it into the Confluence page. It always displays and needs no dependency on anything external, but it is a snapshot: the image shows the diagram exactly as it was when exported and does not change when the diagram does. In a wiki that outlives many system changes, this is the mechanism by which documentation goes wrong - the page still shows a tidy architecture diagram, but it is last year's architecture, and nobody flagged it because the image looks fine.

The live option is to embed the diagram so Confluence renders its current version from the source. When you edit the diagram, the embedded view reflects the change without anyone editing the wiki page, which is the crucial property for documentation that must stay honest over time. The cost is a dependency on the diagram remaining accessible from its link, and on readers having permission to view it. For the many diagrams in a wiki that will keep evolving alongside the systems they describe, that trade is almost always worth making.

Embedding a live diagram step by step

Getting a live diagram into a Confluence page follows a consistent flow. These steps produce a current, self-updating diagram in the page.

• Build or open the diagram in Atlas Diagram Studio at /diagrams so it has a shareable link.
• Set the diagram's sharing so everyone who can read the Confluence page can also view the diagram.
• Copy the diagram's link from the editor.
• On the Confluence page, add an embed via the appropriate macro or by pasting the link and choosing to embed it.
• Size the embedded diagram so it is legible within the page layout rather than cramped or overflowing.
• Verify it renders the current diagram, then make an edit at the source and confirm the page reflects it.
• Add a caption stating what the diagram shows, so it functions as documentation and not just a picture.

When a static image fits better

A static image is the right call when fixity is what you want. If the diagram records a point in time - an architecture as approved on a date, a decision snapshot, a historical state - freezing it as an image is appropriate, because there is nothing to keep current and the image carries no dependency. It also fits when the page must be fully self-contained or when some readers will not have access to the diagram's source, since an embed depends on that source being reachable.

When you go static in Confluence, choose the export format for the destination: a PNG is simple and universally displayed, an SVG stays crisp when zoomed, and a PDF suits an attachment meant for print or download. The export guide at /guides/how-to-export-diagrams-to-png-svg-pdf lays out those trade-offs. Whichever you pick, treat the image as a snapshot with an expiry: if the underlying diagram could change, either schedule a refresh or, better, switch to a live embed so the refresh happens for free. Defaulting to a pasted image out of habit is how good wikis accumulate quietly wrong diagrams.

Keeping a team wiki accurate

The strongest reason to prefer live embeds in Confluence is organizational: a team wiki is read by many and maintained by few, so any diagram that requires a manual refresh will eventually be forgotten. Live embeds remove that step, keeping pages honest without ongoing effort, which matters most precisely in the shared spaces where no single person owns every page. Reserve static images for the deliberate snapshot cases and make the choice consciously each time.

An embedded diagram also earns its keep through the same habits as any documentation diagram: a caption that states what it shows, placement where it answers the reader's current question, and a consistent visual language across the space so the team reads every diagram faster. The cross-tool principles are in the guide on embedding diagrams in docs and wikis at /guides/embedding-diagrams-in-docs-and-wikis, the Notion counterpart is at /guides/how-to-embed-a-diagram-in-notion, and fitting these into a maintained documentation set is covered in the guide on documenting software with diagrams at /guides/how-to-document-software-with-diagrams. Build and share the diagrams from Atlas Diagram Studio at /diagrams, and lean on real-time collaboration so subject-matter experts can keep them correct directly.