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
MDX renders an iframe directly
A .mdx page accepts JSX, so an iframe is just markup, no plugin, no config flag, no sanitizer to route around. Point it at an interactive diagram page and readers pan and zoom inside the docs. This is the opposite situation from READMEs and wikis where HTML gets stripped; in Docusaurus the interactive form is the easy one.
Give the iframe an accessible title, a width of 100 percent, and a height that fits your layout. The framed page must allow embedding, which the Datadef embed page does, chrome-less with a small attribution link to the full diagram.
{/* docs/architecture.mdx */}
<iframe
src="https://datadef.io/embed/my-platform-a1b2c3d4"
title="Platform architecture"
width="100%"
height="560"
style={{border: 'none', borderRadius: '8px'}}
/>
{/* Or the image form, markdown works in MDX too: */}
External images bypass the asset pipeline, and that is the point
Docusaurus processes local images at build time: files you import or require, and everything in static/, are hashed, copied into the build output, and frozen there until the next deploy. External URLs take a different path: the build emits them verbatim into the HTML and never downloads a copy. Nothing about your deploy pins the diagram's pixels.
The consequence is the useful part: a site built and deployed three weeks ago shows the diagram as it is now, because each reader fetches the URL at view time and the image endpoint re-renders when the diagram changes, with a five minute cache lifetime. No rebuild, no redeploy, no docs PR to update a PNG.
Dark mode: ThemedImage or one self-contained image
Docusaurus ships a ThemedImage component that takes a light source and a dark source and swaps them with the active theme; under the hood the useColorMode hook exposes the same signal for custom components. If you maintain light and dark variants of the diagram as two URLs, ThemedImage wires them up in a few lines.
Before maintaining two variants, check whether you need them: an image that carries its own solid background reads acceptably on both themes, and one URL is one fewer thing to keep true. The iframe form sidesteps the question entirely, since the framed page controls its own rendering.
The docs-as-code loop, and the honest limits
A Docusaurus site usually lives in the same repo family as the code it documents, which makes the regeneration loop natural: the Datadef MCP server (registry name io.datadef/mcp) lets an agent like Claude Code update the diagram from what it reads in the repository, invoked after a merge, in the same CI that deploys the docs, or on request during review. Datadef does not watch the repository; the loop runs when an agent call or CI command triggers it. The agent connects with an API key issued to paid plans.
Two limits to state plainly. The embed URLs exist only while the project is shared public; a private project 404s them, docs site included. And the scope is diagrams: prose, API references, and code comments are not something Datadef syncs. For multi-service docs where each service page carries its own diagram, the pattern scales as described in keep microservices docs in sync.
FAQ
How do I embed an iframe in Docusaurus?
Do external images update without rebuilding a Docusaurus site?
How do I show different diagrams for light and dark mode in Docusaurus?
Should I use the iframe or the image form in Docusaurus docs?
Can the diagram in my docs regenerate when the code changes?