Docs & Code Guide

Embed diagrams in BookStack: the iframe allowlist and the editor that cooperates

BookStack takes content security seriously: iframes in page content only survive if their source is on a server-side allowlist, and the WYSIWYG image tools are built around uploaded files. Both defaults can be worked with. An admin adds one line to .env for iframes, or you use the Markdown editor where an external image URL renders directly and stays live, updating within minutes of a diagram edit. Here is the exact configuration and the honest comparison with the drawing tool BookStack already ships.

Try it free
7 min readFor teams documenting in a self-hosted BookStack instance

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

180/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Iframes and ALLOWED_IFRAME_SOURCES

BookStack sanitizes page content and restricts embedded iframes to an allowlist of sources, configured server-side through the ALLOWED_IFRAME_SOURCES option in the .env file. The default list covers a few popular services such as YouTube and Vimeo; anything else is stripped when the page renders. There is no per-page or per-user override, which is the point: embed policy is an admin decision, made once.

To host an interactive diagram embed, the admin adds the diagram host to the list, restarts the app, and the iframe renders for everyone. Readers can then pan and zoom the actual diagram inside the page.

# .env: extend the iframe allowlist (space-separated), then restart BookStack
ALLOWED_IFRAME_SOURCES="https://*.youtube.com https://*.vimeo.com https://datadef.io"

# Then in a page, via the WYSIWYG code view or Markdown editor:
# <iframe src="https://datadef.io/embed/my-platform-a1b2c3d4"
#         style="width:100%;height:480px;border:none"></iframe>

External images: the Markdown editor is the reliable route

BookStack offers two page editors, WYSIWYG and Markdown, selectable per instance or user. Their image handling differs in a way that matters here. The WYSIWYG image tools are built around the image gallery: files you upload and manage inside BookStack. An uploaded copy of a diagram is frozen at upload time, which is exactly the staleness this pattern exists to avoid.

The Markdown editor renders standard image syntax with an absolute URL, hotlinked from the source rather than copied into the gallery. Point it at a Datadef project shared public and the page shows the current diagram: served with an ETag from the last edit and a five minute cache lifetime, so an edit appears within minutes with nobody re-uploading anything.

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

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

The incumbent: diagrams.net is built in, and it is good

BookStack ships a diagrams.net integration, so pages can carry drawings created and edited without leaving the wiki. For one-off sketches owned by a single page, it is genuinely the right tool: no external service, drawings stored with your content, editing a double-click away.

The difference shows after the drawing is made. A diagrams.net drawing is updated when a person remembers to open and redraw it. A live embed points at a source diagram that can also be updated by an agent reading the repository, so the wiki copy follows without anyone opening an editor. For diagrams describing systems that change, that maintenance property is the deciding factor; for everything else, the built-in tool is fine.

Keeping the diagram current

The allowlist was a one-time admin step; the recurring work is keeping the diagram honest, and that loop lives next to the code rather than inside BookStack. An agent wired to Datadef through MCP, registry name io.datadef/mcp, can read the repository after a merge and update the diagram, which every BookStack page embedding it then reflects on the next view. Datadef initiates none of this: no repository watching exists, only an agent call your CI or your team makes, using an API key that paid plans provide.

The failure mode this addresses has a name, wiki rot: pages that were true when written and quietly stopped being true. Diagrams rot fastest, because nobody diffs a picture.

What the allowlist cannot fix

The embed URLs exist only for projects shared public. Self-hosted BookStack instances often hold exactly the content that cannot be public, and for confidential architectures the honest pattern is a static export uploaded to the gallery, refreshed when the system changes, staleness accepted.

Note also what BookStack sanitization does not do: it does not strip external images inserted through Markdown, but scripts in content are blocked by default, and iframe policy is the .env allowlist above. If your admin declines to extend the allowlist, the image form delivers the same live diagram with no configuration at all. The repo-side baseline is covered in embed diagrams in Markdown.

FAQ

How do I allow iframes in BookStack?

Iframe sources are allowlisted server-side through the ALLOWED_IFRAME_SOURCES option in the .env file, which defaults to a few services such as YouTube and Vimeo. An admin adds the embed host to the list and restarts the app; iframes from unlisted sources are stripped at render time.

Can I embed an external image by URL in BookStack?

Yes, through the Markdown editor with standard image syntax and an absolute URL. The image is hotlinked from its source rather than copied into the gallery, so it keeps tracking the source. The WYSIWYG image tools revolve around uploaded gallery files, which are frozen copies.

Does BookStack copy external images into its own storage?

Not when they are referenced by URL in Markdown content; the page hotlinks the source and readers fetch it directly. Files you upload through the image gallery are stored by BookStack and do not change when the original does.

Should I use the built-in diagrams.net integration or an embedded diagram?

Use diagrams.net for one-off drawings owned by a single page; it stores drawings with your content and edits in place. Use a live embed for diagrams of systems that change, because the source can be updated once, by hand or by an MCP-connected agent reading the repository, and every embedding page follows within minutes.

Does an embedded diagram update automatically in BookStack?

The page shows the current image on each view because it hotlinks the source, which is served with a five minute cache lifetime; an edited diagram appears within minutes. The edit itself is made by a person or an agent, not detected automatically from code changes.