Embed diagrams in Outline: image URLs, /embed, and what survives export

Outline's editor is Markdown-compatible, so standard image syntax with an absolute URL renders the image in the document, fetched from the source rather than copied into Outline's storage. That distinction is what keeps it live: Datadef serves the image with an ETag from the diagram's last edit and a five minute cache lifetime, so an edited diagram appears in the document within minutes.

This is different from pasting an image file, which Outline uploads and stores itself. Uploaded copies are frozen; URL references follow their source. For a diagram meant to stay current, always reference, never upload.

![Platform architecture](https://datadef.io/api/embed/my-platform-a1b2c3d4)

<!-- Sized render if the default 1600x1000 at 2x does not fit -->
![Platform architecture](https://datadef.io/api/embed/my-platform-a1b2c3d4?width=2000&height=1250&scale=2)

Outline builds rich interactive embeds automatically when you paste a link from a recognized service: Figma, Google Docs, Loom, and a long list of others unfurl into purpose-built frames. For services not on that list, the /embed command is the general mechanism: it places a link into an embedded frame where the document shows the external page, provided the target permits being framed.

Datadef's embed page allows framing, so /embed with the interactive URL gives readers a pannable, zoomable diagram inside the Outline document, chrome-less except for a small attribution link to the full version. Sites that send X-Frame-Options or a restrictive frame-ancestors policy are the ones that leave an empty frame here.

In an Outline document:
1. Type /embed and press enter
2. Paste: https://datadef.io/embed/my-platform-a1b2c3d4
3. The diagram renders in-place; readers pan and zoom without leaving the doc

Outline exports documents as Markdown, and the two embed forms fare differently. Images that were uploaded into Outline export with instance-relative upload paths, which break the moment the Markdown lives anywhere else. An image referenced by absolute external URL exports as exactly that URL and keeps rendering wherever the Markdown lands: another wiki, a repo, an editor preview.

That makes the external image reference the most portable form of the diagram: live inside Outline, and still live after an export or migration. Embed blocks are an in-app experience and do not carry the same weight in exported Markdown, so documents that must survive export should carry the diagram as an image reference, possibly alongside an embed for in-app readers.

The document now tracks the diagram; the diagram has to track the system, and that is a repo-side loop. Datadef publishes an MCP server under the registry name io.datadef/mcp, and a connected coding agent, Claude Code and Cursor both qualify, can regenerate the diagram from what it finds in the repository after a merge. Nothing is detected for you: Datadef does not watch repos, so regeneration fires when the agent is invoked, from CI or by hand, carrying an API key issued on paid plans.

Architecture pages in a knowledge base are read most by the people who joined last. Keeping those pages true is most of the value, and the wider practice is covered in keeping onboarding docs up to date.

Both embed forms exist only for projects shared public; a private project turns the image URL into a 404 and removes the embed page with it. For confidential architectures, upload a static export into Outline and accept the staleness, or keep the diagram out of the knowledge base.

Outline deserves its credit here: pasting links that become rich embeds is one of its best behaviors, and it embeds Figma or Google Docs artifacts as well as it embeds a diagram. What no wiki does is keep the diagram itself true; that loop always lives with whoever, or whatever, edits the source. The repo-side baseline is covered in embed diagrams in Markdown.

• Embed diagrams in Markdown
• Embed diagrams in Slab
• Embed diagrams in Wiki.js
• Keeping onboarding docs up to date