Embed diagrams in mdBook: raw HTML pass-through with a dark mode that behaves

mdBook renders Markdown with pulldown-cmark, which leaves inline HTML untouched and emits it into the output page as-is. No sanitizer runs afterward. That means an iframe pasted into a chapter renders exactly as written, with no plugin, no preprocessor, and no configuration.

The interactive form is the one to use when readers inspect details: they can pan and zoom the actual diagram inside the book instead of squinting at a fixed PNG. The frame is chrome-less apart from a small attribution link to the source diagram.

<iframe
  src="https://datadef.io/embed/my-platform-a1b2c3d4"
  style="width: 100%; height: 480px; border: none;"
  title="Platform architecture"
></iframe>

mdBook copies files from src into the book output verbatim and never downloads, hashes, or rewrites remote URLs. A Markdown image pointing at an external URL reaches the reader untouched, and the browser fetches it from the source at view time.

That is the property a live embed needs. A Datadef project shared public serves a permanent image URL that re-renders when the diagram changes, with an ETag from the last edit and a five minute cache lifetime. Edit the diagram and the book shows the new version within minutes, with no mdbook build and no redeploy. The first render after an edit can take a few seconds while a headless browser produces it; it is cached after that.

mdBook ships five themes: light and rust are light, while coal, navy, and ayu are dark. A light-background diagram PNG dropped into navy glows like a lightbox. The theme switcher gives you the hook to fix it: the active theme name is set as a class on the html element, so a few CSS rules registered through additional-css in book.toml can style the embed per theme.

The practical treatment is to frame the image as a card under the dark themes: a white background, a little padding, and rounded corners read as deliberate instead of glaring. The iframe form needs none of this, since it shows the diagram with its own page styling regardless of book theme.

<!-- In the chapter -->
<img class="arch-diagram" src="https://datadef.io/api/embed/my-platform-a1b2c3d4" alt="Platform architecture">

/* theme/diagrams.css, registered via additional-css in book.toml */
.arch-diagram { max-width: 100%; }
html.coal .arch-diagram, html.navy .arch-diagram, html.ayu .arch-diagram {
  background: #fff;
  padding: 12px;
  border-radius: 8px;
}

mdBook extends through preprocessors declared in book.toml, programs that rewrite chapter content before rendering. Diagram tooling in this ecosystem usually lives there: mdbook-mermaid, for example, injects the assets that render fenced Mermaid blocks at view time. An embedded diagram needs none of that machinery, because nothing in the chapter has to be transformed: the URL is the integration.

The honest comparison: Mermaid in the same commit is the right call for small flows that belong to one chapter, and it reviews well in diffs. Generated layout struggles past roughly twenty nodes or when zones and grouped detail matter, which is where the embedded form with a real layout takes over. Where each approach tops out is covered in docs-as-code diagram limits.

The embed removes the re-export step; the diagram edit remains, and it happens entirely outside the book. Point an MCP-capable agent at the Datadef server, registry name io.datadef/mcp, and it can bring the diagram in line with the repository after a merge, no mdbook build involved. Be clear about the trigger, though: Datadef does not monitor repositories, so a CI job or a person invokes the agent, and one call later the book shows the new architecture. Agent API keys exist on paid plans.

Both embed forms exist only for projects shared public; a private project turns the URLs into 404s. For confidential systems, commit a static export next to the chapter and accept the staleness. And mdBook has no link checker for remote URLs by default, so a dead embed shows up as a broken image, not a failed build.

• Embed diagrams in Markdown
• Embed diagrams in Docsify
• Embed diagrams in MkDocs
• Docs-as-code diagram limits