Share

Embedding

Architecture screenshots rot: the diagram changes, the README keeps the old picture, and readers trust it anyway. An embed is a permanent URL that always renders the current diagram. Paste it once into a README or a docs page and it stays correct as the canvas changes: no re-export, no stale screenshot.

What you paste

README.md

## Platform architecture

![Customer 360 Platform](https://datadef.io/api/embed/customer-360-platform)

_Embedded from Datadef, not exported._

What readers see

Platform architecture

Customer 360 Platform, a live Datadef embed rendered from its permanent URL

Embedded from Datadef, not exported.

The rendered pane is live: the same /api/embed endpoint your diagrams get.

How it works

  1. 1Open Embed from the canvas top bar and switch the project to Anyone with the link.
  2. 2Copy the form your doc takes: the markdown image for GitHub and GitLab READMEs, the iframe for docs sites and Notion, or the bare image URL.
  3. 3Paste it once. Readers always see the current diagram, and edits show up in the embed within minutes.
  4. 4To take an embed offline, make the project private again; every embed of it stops resolving.

The Embed dialog

Open Embed from the canvas top bar. The dialog holds the public toggle, a live preview loaded from the same URL a README would use, and three copy-ready snippets:

FormUse it inWhat it renders
MarkdownGitHub and GitLab READMEs, issues, docsA live image of the diagram
iframeDocs sites, Notion, ConfluenceA pan-and-zoom viewer, chrome-less
Image URLAnywhere that takes a pictureThe bare image

GitHub strips iframes from READMEs, so the markdown image is the right form there. The iframe is for places that allow it and where readers benefit from zooming into a large diagram.

The URLs

![Architecture](https://datadef.io/api/embed/<publicSlug>)

<iframe src="https://datadef.io/embed/<publicSlug>"
        width="100%" height="600" style="border:0" loading="lazy"></iframe>

The image endpoint accepts rendering parameters: ?format=png|jpeg&width=600..4000&height=400..4000&scale=1..3. Defaults: PNG, 1600x1000, at 2x scale. The endpoint sends CORS *, so it works from any origin.

How current the embed is

  • An edited diagram shows up in the embed within minutes. The image carries an ETag tied to the canvas's last update and a five-minute cache lifetime, so consumers re-fetch quickly without hammering the renderer.
  • The first render after an edit can take a few seconds: a headless browser draws the canvas. Subsequent loads are cached.

The public-project requirement

Embeds require a public project

Embed URLs resolve on the project's public slug, so the project must be set to Anyone with the link. Flip the project back to private and every embed of it stops working: the URLs return 404 wherever they were pasted.

This is a real limitation for confidential architectures: an embedded diagram is a public diagram. For internal-only docs, keep the project private and share the invite-based links instead. Public visitors can view only; embedding never exposes editing.

Further reading