Embed diagrams in Coda: /embed, the Force option, and synced-page behavior

Typing /embed and pasting a URL creates an embed block, and Coda resolves what to show through Iframely, a third-party embed service that knows how to render thousands of sources. A direct image URL displays as the image; a page URL displays framed. Either way the block points at your URL rather than storing a copy, which is what keeps the content current.

Both Datadef URL forms work here. The image endpoint renders the diagram as a PNG served with an ETag from the last edit and a five minute cache lifetime, so an edited diagram shows in the doc within minutes. The interactive page gives readers pan and zoom inside the doc. Blocks resize by dragging their handles, so a wide platform diagram can take the full page width.

Image form (displays as a live PNG):
/embed  ->  https://datadef.io/api/embed/my-platform-a1b2c3d4

Interactive form (pan and zoom in an embedded frame):
/embed  ->  https://datadef.io/embed/my-platform-a1b2c3d4

Formula form, usable in canvas formulas and buttons:
Embed("https://datadef.io/embed/my-platform-a1b2c3d4", 900, 520)

Some sites resist framing, and for those the embed block offers a Force option, also available as the fourth argument of the Embed formula. A forced embed loads the URL in a sandboxed iframe, but it starts in a disabled state: each user clicks the block and approves the domain before the content renders. The approval is per domain and per user, and once given it covers that domain across docs.

You should not need Force for a Datadef embed, since the embed page permits framing. Where the option earns its place is internal tools and dashboards that send restrictive framing headers; knowing it exists saves an afternoon of wondering why a URL renders as a bare link. If a forced embed stays blank after approval, the target site is refusing frames outright, and no Coda setting overrides that.

Coda docs increasingly share content through synced pages, where one page is maintained in a source doc and mirrored into others. An embed block on a synced page behaves the way you would hope: the mirror shows the same block pointing at the same URL, so every doc that syncs the architecture page shows the same current diagram. Fix the diagram once and every synced copy follows.

The one wrinkle is approval: because forced-embed approval is per user, a teammate opening the synced copy approves the domain themselves before a forced embed renders. Standard embeds, including Datadef ones, carry no such step and simply render for everyone.

Synced pages multiply what the embed shows, which raises the stakes on the source diagram being right. Keeping it right can be delegated: an agent using the io.datadef/mcp server from the MCP registry reads the repository after each architecture-changing merge and updates the diagram, and every doc syncing the page follows at once. The mechanics stay honest, Datadef watches nothing and detects nothing; the update is one agent invocation, authorized by an API key on a paid plan.

Design docs are where this bites hardest in Coda: the spec ships, the system evolves, the diagram in the spec stays put. The wider practice is covered in keeping design docs up to date.

Embed URLs exist only for projects shared public. Flip the project private and the image 404s while the embed page disappears with it; for confidential architectures, upload a static export into the doc and accept the staleness.

Credit where due: Coda plus Iframely embeds nearly anything with a URL, and for recognized services the rendering is genuinely rich. The pattern in this guide is not Coda-specific magic, it is choosing a source that stays current behind a stable URL. The Markdown and README variant of the same pattern is covered in embed diagrams in Markdown.

• Embed diagrams in Markdown
• Embed diagrams in Notion
• Embed diagrams in Slab
• Keeping design docs up to date