Embed diagrams in Wiki.js: what renders by default and what the sanitizer strips

Standard Markdown image syntax with an absolute URL renders in Wiki.js without touching a single setting. The image is fetched from the source by each reader, not copied into wiki storage, so it keeps tracking the source.

Point it at a Datadef project shared public and the wiki page shows the current diagram: the image is served with an ETag from the diagram's last edit and a five minute cache lifetime, so an edit shows up within minutes. No page save, no re-upload, no asset manager involvement.

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

<!-- Sized render for wide pages (params optional) -->
![Platform architecture](https://datadef.io/api/embed/my-platform-a1b2c3d4?width=2400&height=1400&scale=2)

Rendered content in Wiki.js flows through a rendering pipeline of modules, and the one that decides an iframe embed is html-security, which sanitizes the final HTML with DOMPurify. With its Sanitize HTML option enabled, the default, iframes are stripped from the output. The switch lives in the admin area under Rendering, in the HTML section, under Security.

Turning Sanitize HTML off is an instance-wide decision, not a per-page one, and it is exactly what it sounds like: every editor on the wiki can then inject arbitrary HTML into pages. On a wiki where every editor is trusted, that may be acceptable. On anything larger, leave the sanitizer on and use the image form, which needs no exemption and carries the same freshness.

<!-- Renders only if Sanitize HTML is disabled in
     Administration > Rendering > HTML > Security -->
<iframe
  src="https://datadef.io/embed/my-platform-a1b2c3d4"
  style="width: 100%; height: 480px; border: none;"
  title="Platform architecture"
></iframe>

Wiki.js offers multiple editors per page, and the two common ones handle embeds differently. The Markdown editor is the direct route: paste the image syntax or, where allowed, the iframe tag, and the preview shows the result. The visual editor works through dialogs; inserting an image by URL means using its image dialog rather than typing syntax.

For pages that carry architecture diagrams, the Markdown editor is the safer habit: the embed is visible as plain text in the page source, survives editor switches, and diffs cleanly in page history when someone changes the URL.

The wiki now shows whatever the diagram is; keeping the diagram true to the system is the remaining work, and it never touches Wiki.js. An agent hooked to the Datadef MCP server, registry name io.datadef/mcp, can make that edit from the repository, redrawing the diagram after a merge that touched the services it covers, and every wiki page holding the embed follows. To be plain about the mechanics, Datadef never polls repositories and detects nothing by itself; the agent runs when your pipeline or your team starts it, authenticated with an API key from a paid plan.

The wider habit of keeping wiki content aligned with reality, beyond diagrams, is covered in keeping the internal wiki in sync.

The embed URLs exist only for projects shared public. A self-hosted Wiki.js instance often exists precisely because content must stay inside the network, and for confidential architectures the honest answer is an uploaded static export, refreshed when the system changes, staleness accepted.

Wiki.js also ships a diagrams integration of its own via draw.io style editing, and for one-off drawings owned by a single page it is perfectly serviceable. The difference is what happens after the drawing: an embedded, source-backed diagram can be regenerated by an agent when the code changes, while a hand drawing waits for a human to remember it. The Markdown baseline for READMEs and repos is covered in embed diagrams in Markdown.

• Embed diagrams in Markdown
• Embed diagrams in BookStack
• Embed diagrams in Outline
• Keeping the internal wiki in sync