Embedding Diagrams in Docs and Wikis

Embedding is the practice of placing a live diagram inside another page - a document, a wiki article, a knowledge base - so that what readers see is the actual diagram, not a picture of it. Technically it is usually an iframe or embed block that renders the diagram in place; practically it is the difference between a diagram that stays current and one that rots. When you paste a static image, you have exported a snapshot that is correct only at export time and drifts silently thereafter. When you embed, the page shows the living diagram, and updates to the source appear on the page automatically.

This guide explains how embedding works, why it beats pasting images, and how to embed diagrams so your documentation stays trustworthy. The environment is Atlas Diagram Studio at /diagrams, where a diagram is a live object you can embed rather than only export, and where - for data-linked and live diagrams - the embedded version can reflect real, current data. It connects directly to the guide on documenting software with diagrams, which covers the broader question of keeping documentation diagrams accurate over time.

How embedding works

An embedded diagram is rendered from the source rather than copied into the page. You take an embed link or code - typically an iframe pointing at the live diagram - and drop it into your document or wiki, which then displays the diagram inline. Because the page holds a reference to the source, not a frozen copy, whatever the diagram currently shows is what readers see. Edit the diagram in the studio, and every page that embeds it updates without anyone touching those pages. One change propagates everywhere the diagram appears.

This reference-not-copy model is the whole point, and it mirrors how data binding works within a diagram. Just as a bound shape shows the current value from its source, an embedded diagram shows the current state of the diagram from its source. The consequence is that your documentation and your diagram never diverge: there is one canonical diagram, and the wiki simply displays it. Compare this to the image workflow, where every page has its own frozen copy that must be re-exported and re-pasted whenever the diagram changes - a chore so tedious that in practice it never happens, which is exactly why documentation diagrams go stale.

Why embedding beats pasting an image

The advantages of embedding over static images stack up quickly, and each one addresses a real failure of the paste-an-image habit.

• The embedded diagram stays current - edit the source once and every page showing it updates, with no re-export.
• There is a single source of truth, so documentation and diagram never drift apart into conflicting versions.
• For data-linked diagrams, the embed can show live data, so the picture on the wiki reflects real, current values.
• Readers can often interact with an embed - pan, zoom, follow links - where a flat image only sits there.
• You avoid the tedious re-export-and-re-paste chore that, because nobody does it, is why image-based diagrams rot.
• Updates propagate everywhere at once, so the same diagram embedded in five pages is consistent across all five.

Embedding live and data-linked diagrams

Embedding is most powerful when the diagram itself is live. A static architecture diagram embedded in a wiki already beats a pasted image because structural edits propagate. But a data-linked architecture diagram - one whose nodes show current uptime, latency, or version - becomes something else entirely when embedded: a live status view sitting right inside your documentation, updating on its own. The wiki page stops being a description of the system and becomes a window onto it, without anyone maintaining the numbers by hand.

This is where the capabilities compound. A live data diagram that would go stale as an exported image stays perpetually current as an embed, so the operational overview on your team's wiki reflects reality all day. The discipline is to embed rather than export whenever the reader needs the current truth, and to reserve exports for point-in-time records. Build the diagram and its bindings in Atlas Diagram Studio at /diagrams, embed it where people read, and the documentation maintains itself. The guides on live data diagrams and on keeping diagrams in sync with your data cover the source side; this embedding step is what delivers that live diagram to its readers.

Practical embedding habits

A few habits keep embedded diagrams working well. Embed at a sensible size and let the diagram be interactive where the platform allows, so readers can zoom into a dense area rather than squinting at a fixed thumbnail. Give each embed a short caption in the surrounding page, just as you would an image, stating what it shows and what to notice - an embed still benefits from the words around it that turn a diagram into documentation. And place the embed right where the text discusses it, not in a distant appendix.

Mind access and permissions: an embedded diagram is only visible to readers who are allowed to see it, so make sure the diagram's sharing settings match the audience of the page it lives on. For a public knowledge base, the diagram needs to be viewable publicly; for an internal wiki, it should stay internal. When in doubt, check that a reader without special access sees the diagram as intended. Handled well, embedding turns Atlas Diagram Studio diagrams at /diagrams into living components of your documentation rather than dead images, and connects to the broader documentation practice in the guide on how to document software with diagrams. The diagram-tools overview at /diagram-tools shows the range of diagram types you might embed.