Embed a diagram in Obsidian: markdown images, iframes, and what changes on Publish

Obsidian has two link syntaxes and only one of them takes an external URL. The wikilink embed, ![[architecture.png]], resolves names inside the vault: it embeds a file that exists on disk. An external diagram needs standard markdown image syntax, , which renders in both reading view and live preview.

This is the mistake behind most "external image not showing" moments in Obsidian: ![[https://...]] silently fails because the wikilink resolver treats the URL as a filename it cannot find. Switch to markdown syntax and it renders.

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

<!-- This does NOT work for external URLs: -->
![[https://datadef.io/api/embed/my-platform-a1b2c3d4]]

<!-- Interactive version, raw HTML works inside notes: -->
<iframe src="https://datadef.io/embed/my-platform-a1b2c3d4" width="100%" height="500"></iframe>

Obsidian renders raw HTML in markdown, and its own help documents embedding web pages with an iframe tag. Point one at an interactive diagram page and the note gets a pannable, zoomable view of the current diagram, useful when the note is where you actually think about the system. The framed site must allow embedding; sites that send X-Frame-Options stay blank, while pages built for embedding render.

For most notes the plain image is enough and lighter. Both forms follow the source: the image is served with a five minute cache lifetime, so an edited diagram shows up in your notes within minutes.

An Obsidian vault is files on disk, and external embeds are the one part of a note that does not travel with it. Offline, the image placeholder is what you get. Notes you rely on in no-network situations, an incident runbook read from a train, should carry a committed export next to the live embed, updated when it matters.

Sync between devices is unaffected, since the note stores only a URL, and the same line renders identically on desktop and mobile when the network is there.

What renders in your vault does not automatically render on an Obsidian Publish site. Community reports over the years include iframes blocked by content security policy on published sites and external images failing over plain http, which Publish does not load; https URLs are the baseline.

The practical guidance: the https image form is the safer of the two on Publish, and whatever you choose, check the published page rather than trusting the in-app preview. If the diagram must be interactive for public readers, link out to the diagram page instead of framing it.

The note now shows whatever the diagram is; keeping the diagram truthful is the remaining work. Datadef ships an MCP server (registry name io.datadef/mcp), so an agent with repository access, Claude Code or Cursor, can update the diagram from what it reads in the code when you ask it to, or from CI after merges. Datadef does not watch repositories; the update happens when an agent call or CI command requests it. The API key behind it comes from the paid plans.

The embed URLs require the project to be shared public and 404 if it goes private, which matters for personal vaults documenting employer systems: keep confidential detail out of the shared diagram. The wider problem of knowledge living in one head, which vaults both help and hide, is the subject of tribal knowledge in engineering teams.

• Embed diagrams in Markdown
• Embed diagrams in Docsify
• Embed diagrams in mdBook
• Tribal knowledge in engineering teams