See it as a diagram
Everything below, as a diagram you can edit. Describe yours and see it in seconds.
No account needed · Editable canvas, not a picture
VitePress parses your pasted HTML as a Vue template
In VitePress, Markdown is first rendered to HTML and then processed as a Vue single file component. Raw HTML in a page is legal, but it is Vue template syntax, not plain HTML. Two consequences matter for embeds. First, double curly braces anywhere in the text are treated as Vue interpolation, so a URL or caption containing them breaks the compile; wrap the offending element in v-pre if you ever hit this. Fenced code blocks are exempt because VitePress wraps them in v-pre automatically.
Second, the Vue compiler is stricter than a browser. Browsers silently repair an unclosed tag; the Vue template compiler fails the build instead. So close the iframe tag explicitly, keep attribute quotes balanced, and the snippet compiles like any other template. No ClientOnly wrapper and no v-if guard is needed: a static img or iframe renders identically during server-side generation and in the browser, so there is nothing to defer to the client.
External images bypass the asset pipeline, which is the point
When a Markdown image points at a relative path, Vite processes it as an asset: the file is hashed, copied into the build output, and frozen at build time. An absolute http or https URL takes the other branch: VitePress leaves it untouched, and each reader fetches the image from the source when the page is viewed.
That untouched branch is what makes a live embed possible. A Datadef project shared public serves a permanent image URL, re-rendered when the diagram changes, with an ETag from the diagram's last edit and a five minute cache lifetime. Edit the diagram and the docs page shows the new version within minutes, without a commit, a CI run, or a redeploy of the VitePress site.
<!-- Live image: absolute URL, so Vite's asset pipeline never touches it -->  <!-- Sized render for a wide layout (params optional) --> 
The iframe form when readers need pan and zoom
Because raw HTML is allowed, an interactive embed is one tag. Readers can pan and zoom the actual diagram, which beats a scaled image for column-level lineage or dense service maps. The frame is chrome-less apart from a small attribution link to the full diagram.
<iframe src="https://datadef.io/embed/my-platform-a1b2c3d4" style="width: 100%; height: 480px; border: none; border-radius: 8px;" title="Platform architecture" ></iframe>
Vue template rule
The dead-link checker will not catch a dead embed
VitePress fails the build on dead internal links, and ignoreDeadLinks exists to soften that. External URLs are a different story: the checker never validates them. An image URL that starts returning 404 will pass every build and simply render as a broken image in production.
The realistic way that happens with a Datadef embed is the project being flipped from public to private, which removes the public slug and turns the URL into a 404. Treat the visibility setting as part of your docs infrastructure: if the diagram is embedded in published docs, it stays public, and if it must go private, remove the embed in the same change.
Keeping the diagram itself current
The embed removes the re-export step, not the edit step. Someone still updates the diagram when the architecture changes, and with the VitePress build out of the loop, that edit is the only moving part left. The lightweight loop is manual editing in Datadef. The heavier loop hands the edit to a coding agent: Datadef exposes its diagram tools over MCP, registry name io.datadef/mcp, and Claude Code or Cursor connected to that server can redraw the diagram from what a merge changed. None of this is automatic detection, Datadef never looks at your repository on its own; the redraw happens when your CI job or a teammate invokes the agent. The API key that authorizes an agent is created in settings, on paid plans.
Deciding when that call is worth making is its own question, covered in when to regenerate an architecture diagram. The general pattern is living documentation: the doc follows the source instead of memory.
Where this breaks in VitePress
Both embed forms exist only for projects shared public. Confidential architectures need a different trade: commit a static export into the repo and accept staleness, or keep the diagram out of public docs entirely.
VitePress also has a strong in-repo alternative: Mermaid via a markdown-it plugin keeps small flows in the same commit as the prose, which is genuinely the right call for a ten node flowchart. Generated Mermaid layout struggles past roughly twenty nodes, zone groupings, and column detail, which is where an embedded diagram with a real layout earns its place. The Markdown-file baseline, including GitHub rendering, is covered in embed diagrams in Markdown.
FAQ
How do I embed an iframe in VitePress?
Does VitePress process external images at build time?
Why did my VitePress build fail after I pasted an embed snippet?
Will the VitePress dead-link checker catch a broken diagram embed?
Does an embedded diagram update automatically in VitePress?