Embed diagrams in Notion: a live view instead of a pasted screenshot

Notion gives you two mechanically different routes to the same result. The first is the embed block: paste a diagram URL on an empty line and Notion offers three choices, Dismiss, Create bookmark, or Create embed. Pick Create embed and the page renders inside an iframe, so readers can pan and zoom the actual diagram without leaving Notion. Typing /embed and pasting the URL into the dialog builds the same block.

The second route is an image block pointed at a URL. Type /image, switch to the Embed link tab, and paste a URL that serves a PNG. Notion renders it like any uploaded image, except the pixels come from the source on view instead of from a file frozen at paste time.

A Datadef project shared public has a URL for each route: an interactive page for the embed block, and a permanent image endpoint for the image block. The image endpoint also takes sizing parameters when the default 1600x1000 render at 2x does not fit the page.

Interactive page, for the embed block (paste, then "Create embed"):
https://datadef.io/embed/my-platform-a1b2c3d4

Image URL, for /image then the "Embed link" tab:
https://datadef.io/api/embed/my-platform-a1b2c3d4

Sized image for a full-width Notion block (params optional):
https://datadef.io/api/embed/my-platform-a1b2c3d4?format=png&width=2400&height=1400&scale=2

Notion renders an embed inside a sandboxed iframe and lets you drag the block edges to set its width and height, so a wide pipeline diagram can take the full column while a small schema sits next to text. One failure mode is specific to iframes: a site that sends X-Frame-Options or a restrictive frame-ancestors header refuses to load inside Notion and leaves a grey box. Datadef's embed page allows framing, so the diagram renders with pan and zoom, chrome-less except for a small attribution link to the full version.

The embed block earns its weight on pages where readers inspect details: column-level lineage, edge labels, zone boundaries. Zooming a live canvas beats squinting at a scaled image, and the reader who needs to edit is one click from the source diagram.

When you add an image by link, Notion does not copy the file into its own storage the way it does with uploads. The block keeps referencing your URL instead of storing a copy, so what readers see is whatever the source serves at view time. That detail is what keeps the image live: Datadef serves it with an ETag derived from the diagram's last edit and a five minute cache lifetime, so an edited diagram shows up in Notion within minutes, without anyone touching the block.

The endpoint accepts format png or jpeg, width from 600 to 4000, height from 400 to 4000, and scale from 1 to 3. A diagram in a full-width block on a wide monitor is worth a 2400 pixel render; the default is already sharp for a normal column.

One timing note: the first render after an edit is produced by a headless browser and can take a few seconds. Every view after that is cached and fast.

Notion's PDF export renders image blocks but not the live content of embed blocks, so a page that must survive export, a runbook, an audit pack, an onboarding doc someone prints, should carry its diagrams as images. The same preference applies to public Notion sites where load time matters: an image is one request, while every embed block boots a full page in an iframe.

Freshness is not part of this decision. Both forms follow the source diagram, so the choice is about how the page is read, not about which copy is current.

The embed removes the re-paste step, not the edit step. Someone still has to update the diagram when the system changes. The lightest loop is manual: edit the diagram in Datadef, and every Notion page that shows it follows within minutes.

The heavier loop hands the edit to the agent that changed the code. Datadef ships an MCP server, registry name io.datadef/mcp, so an agent like Claude Code or Cursor connected to it can create and update the diagram from what it reads in the repository: after a merge, in a scheduled CI job, or on request during review. To be precise about what this is not: Datadef does not watch your repository, and nothing detects code changes by itself. The regeneration is one agent call or one CI command away, which in practice is close enough for a wiki. Connecting an agent needs an API key, available on paid plans.

This is the pattern living documentation names: the doc follows the source instead of somebody's memory. The data platform variant, where schemas and pipelines change daily, has its own guide on keeping data documentation in sync.

The embed URLs exist only for projects shared public. Flip the project private and both forms stop working: the image returns a 404 and the interactive page goes with it. For confidential architectures that trade-off is real, and a static export uploaded into a locked Notion page may genuinely be the right call, accepted staleness included.

Notion also deserves its credit: it embeds nearly anything with a URL, so the pattern in this guide works with any tool that serves a live diagram page. What differs per tool is everything above: whether it allows iframes, whether its image URLs are permanent, and whether an edit actually propagates. The README variant of the pattern, where GitHub strips iframes and the image URL is the only option, is covered in embed diagrams in Markdown.

• Embed diagrams in Markdown
• Keeping data documentation in sync
• Living documentation
• Data pipeline diagram generator