Docs & Code Guide

Embed diagrams in Slab: image URLs, iframe paste, and unfurl limits

Slab keeps its editor deliberately simple, but it leaves the two doors an architecture diagram needs: a pasted public image URL becomes an image in the post, and pasted iframe code unfurls for source hosts a workspace admin has allowed. Point either at a diagram that stays current behind a stable URL and the post follows it, updating within minutes of an edit instead of aging like a pasted screenshot. Here is how each route behaves, including the admin step the iframe route needs, and where the integration unfurls reach their limit.

Try it free
6 min readFor teams whose engineering knowledge base lives in Slab

See it as a diagram

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

157/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

The image route: paste a public URL

Slab documents image insertion by URL directly: copy and paste the URL of a publicly accessible image and it becomes an image in the post. The public-accessibility requirement fits the embed pattern, since a Datadef project shared public serves exactly that: a permanent, credential-free image URL that re-renders when the diagram changes.

Once placed, the image handles like any other in Slab: default width with resize options to half or full width, centered by default, caption underneath if you want one. Full width is the right call for platform diagrams; the default 1600x1000 render at 2x stays sharp there.

Paste directly into a Slab post:
https://datadef.io/api/embed/my-platform-a1b2c3d4

Sized render if the layout needs more pixels:
https://datadef.io/api/embed/my-platform-a1b2c3d4?width=2400&height=1400&scale=2

The iframe route for pan and zoom

Slab's editor recognizes iframe HTML pasted into a post for embeddable content, which is the door for the interactive form: paste an iframe pointing at the diagram's embed page and readers pan and zoom the actual diagram inside the post, chrome-less except a small attribution link to the full version.

The gate to know about: Slab only unfurls a pasted iframe when its source host is on the workspace allowlist, and admins have full control over which hosts are allowed. Ask a Slab admin to allow datadef.io before rolling this route out; until then the paste stays a code snippet. A target site refusing frames with X-Frame-Options is the rarer second failure, and not this one, since the Datadef embed page permits framing. When the admin conversation is not worth having, the image URL route above renders with no approval step at all.

<iframe
  src="https://datadef.io/embed/my-platform-a1b2c3d4"
  width="100%"
  height="480"
></iframe>

Integration unfurls, and where they stop

Slab unfurls links from its supported integrations into rich previews: paste a GitHub or Figma link and the post shows context beyond a bare URL. The list is real but finite, and a tool outside it gets a plain link, not a rendered preview. That is where the two generic routes above matter: an image URL and an iframe work independent of any integration listing, so a diagram source does not need to be on the list to live in a Slab post.

Slab also supports Markdown shortcuts while typing, so writers who think in Markdown can produce headings and emphasis without leaving the keyboard. Image references, however, arrive by paste rather than by Markdown syntax, which is a small workflow difference from Markdown-native wikis worth knowing before you migrate content.

Freshness: what to verify in your own workspace

The freshness of the image route depends on the post fetching your URL at view time rather than serving a copy frozen at paste time. Slab's requirement that the URL be publicly accessible points at hotlinking, and the iframe route is unambiguous: the frame loads the live page on every view. A one-minute verification settles it for your workspace: paste the image URL into a post, edit the diagram, reload the post a few minutes later. If the new version shows, the route is live; if not, the iframe form, once an admin allows the host, is the reliably live view.

Datadef's side of the freshness contract is fixed either way: the image is served with an ETag from the diagram's last edit and a five minute cache lifetime, and the first render after an edit can take a few seconds while a headless browser produces it.

Verify once, then trust it

One edit-and-reload test in your own workspace tells you exactly how your posts behave. It is a better foundation than any doc page, this one included.

Keeping the diagram current, and the honest limits

The post follows the diagram from here on; what remains is making the diagram follow the system. That edit can come from a person in the Datadef editor, or from a coding agent that carries the Datadef MCP server, registry name io.datadef/mcp, in its toolset: it reads the repository and redraws the diagram after a merge, and Slab simply shows the new render. Because Datadef does not watch repositories, the redraw waits for your CI or your team to trigger the agent; API keys for agents are a paid-plan capability.

The limits: embed URLs exist only for projects shared public, and a private project returns 404, so confidential architectures should use uploaded static exports with accepted staleness. Architecture pages in a knowledge base earn their keep during onboarding most of all; the wider practice is covered in keeping onboarding docs up to date, and the repo-side baseline in embed diagrams in Markdown.

FAQ

How do I embed an image by URL in Slab?

Copy and paste the URL of a publicly accessible image into a post; Slab inserts it as an image. It can then be resized to half or full width and captioned. A Datadef image URL such as https://datadef.io/api/embed/your-slug meets the public-accessibility requirement.

Does Slab support iframes?

Yes, behind an admin gate: pasted iframe HTML only unfurls when the iframe source host is allowed by a workspace admin, who controls the allowlist of embeddable hosts. Ask an admin to allow the diagram host first; an unallowed host stays a code snippet. The secondary failure is a target site refusing frames with X-Frame-Options. A pasted public image URL is the route that needs no admin.

Do Slab unfurls work for any URL?

No, rich unfurls come from a finite list of supported integrations; links from other tools stay plain links. Diagram sources outside the list still embed through the generic routes: a pasted public image URL or pasted iframe code.

Does an embedded diagram stay current in Slab?

The iframe form loads the live page on every view, so it always shows the current diagram. For the image form, verify in your workspace once: paste the URL, edit the diagram, and reload a few minutes later. Datadef serves the image with a five minute cache lifetime, so a live route shows edits within minutes.

Can I embed a private diagram in Slab?

Not live: Slab image-by-URL insertion needs a publicly accessible URL, and Datadef only serves those for public projects. For a confidential architecture, insert the exported image into the post the ordinary way and treat it as a snapshot; the post keeps rendering it, but only a fresh paste after the next export brings it up to date.