Embed diagrams in SharePoint: the domain allowlist and the two web parts

The modern-page Embed web part renders external content in an iframe, and it checks the target domain against a site-collection allowlist before rendering anything. That allowlist lives under Site settings, in Site Collection Administration, on the HTML Field Security page. It offers three modes: block embedding entirely, allow contributors to insert iframes from any domain, or allow iframes only from a listed set of domains, which is the mode most tenants run.

Changing the list requires site collection administrator rights, so plan for one small governance step: ask the site admin to add the diagram host before authors paste embed code. Until the domain is listed, the web part refuses the embed with a message that the site does not allow content from that domain. Note also that SharePoint only embeds from HTTPS URLs.

The Embed web part accepts a URL or an embed code, and the embed code must be iframe-based: snippets built from script tags do not run on modern pages. That rule is a feature for this use case, because the diagram embed is a plain iframe with no script involved.

Readers get the interactive form inside the page: pan and zoom on the actual diagram, chrome-less except a small attribution link to the full version. The frame shows the current diagram on every page view, so an edit made in the source appears within minutes without the page being republished.

<!-- Paste into the Embed web part after datadef.io is added to
     Site settings > HTML Field Security allowed domains -->
<iframe
  src="https://datadef.io/embed/my-platform-a1b2c3d4"
  width="100%"
  height="480"
  frameborder="0"
  title="Platform architecture"
></iframe>

When the allowlist conversation is not worth having, the Image web part takes the quieter path: it accepts a link that points directly at an image file, external hosts included. Point it at the diagram's image URL and the page shows a live PNG, fetched from the source when the page is viewed.

Datadef serves that URL with an ETag from the diagram's last edit and a five minute cache lifetime, so an edited diagram appears on the SharePoint page within minutes. The URL also takes sizing parameters, useful for full-width sections on wide screens: format png or jpeg, width 600 to 4000, height 400 to 4000, scale 1 to 3.

Image web part -> From a link:
https://datadef.io/api/embed/my-platform-a1b2c3d4

Sized for a full-width section:
https://datadef.io/api/embed/my-platform-a1b2c3d4?width=2400&height=1400&scale=2

Everything above describes modern pages. Classic pages predate the Embed web part and handled external content through Content Editor and Script Editor web parts, which accept raw markup and are progressively restricted or disabled in many tenants. If your intranet still runs classic pages, the pragmatic move is to host the architecture page as a modern page even if the rest of the site has not migrated, and get the Embed and Image web parts with it.

You asked the site admin for one allowlist entry; the other half of the deal is that the diagram behind the frame stays true. That half belongs to whoever changes the system: after a merge, an agent holding the Datadef MCP server configuration, registry name io.datadef/mcp, can read the repository and refresh the diagram to match, and the SharePoint page reflects it without being republished. No repository watching happens on Datadef's side, ever. A CI stage or an engineer makes the call explicitly, and the agent authenticates with a key that requires a paid plan.

The limits are real. Embed URLs exist only for projects shared public, and organizations on SharePoint often have confidentiality requirements that rule that out; for those architectures, upload a static export to the site assets and accept the staleness. Security-sensitive diagrams have their own discipline, covered in keeping security architecture docs current, and the repo-side baseline lives in embed diagrams in Markdown.

• Embed diagrams in Markdown
• Embed diagrams in Confluence
• Embed diagrams in Azure DevOps Wiki
• Keeping security architecture docs current