Embed a diagram in MkDocs: Python-Markdown lets iframes through by default

Where Hugo makes you flip an unsafe flag and READMEs strip HTML outright, Python-Markdown emits inline HTML as written. An iframe in a MkDocs page renders on the built site with zero configuration, which makes the interactive embed the low-effort option here: readers pan and zoom the current diagram inside your docs.

The plain markdown image works too, and pointed at a live URL it stays current the same way. Both forms follow the source diagram, so the choice is about reading experience, not freshness.

<!-- docs/architecture.md : both render with a stock MkDocs config -->

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

![Platform architecture](https://datadef.io/api/embed/my-platform-a1b2c3d4){ width="900" }

The curly-brace attributes on the image above come from the attr_list extension, part of Python-Markdown but off until you enable it in mkdocs.yml under markdown_extensions. With it on, any image takes width, height, class, or arbitrary attributes inline, which is how you fit a wide diagram to your content column without HTML.

For a sharper source behind that display size, the image endpoint takes its own render parameters: format png or jpeg, width 600 to 4000, height 400 to 4000, scale 1 to 3, defaulting to 1600x1000 at 2x.

Material for MkDocs documents a figure pattern for exactly this case: enable md_in_html alongside attr_list, wrap the image in a figure element with markdown="span", and add a figcaption. The result is a centered, captioned diagram that matches the theme, with the caption carrying the one sentence of context every architecture diagram needs, what this view shows and what it leaves out.

Material handles light and dark palettes site-wide; an embedded image that ships its own background stays legible across both, worth a quick check in your dark palette before publishing.

The build copies docs/ into site/ and rewrites internal links, but an external image URL or iframe src is emitted verbatim; nothing is downloaded or snapshotted at build time. The deployed site therefore shows the diagram as it is at view time, not as it was at deploy time. With the image served under a five minute cache lifetime, an edit reaches your published docs within minutes, no rebuild involved.

This is the property that separates a live embed from the committed-PNG workflow, where every diagram change costs an export, a commit, and a deploy, and skipping that cost is how diagrams rot.

The remaining loop is updating the diagram when the system changes. Datadef ships an MCP server (registry name io.datadef/mcp): an agent with repository access can update the diagram from what it reads in the code, invoked after a merge, in the CI job that builds your docs, or on request. Datadef does not watch repositories, so the trigger is always yours; a docs pipeline that regenerates the diagram before mkdocs build is a natural place for it, alongside the docs checks in CI that catch the prose. An agent API key, which requires a paid plan, closes the loop.

Limits, plainly: the embed URLs exist only for projects shared public, and 404 when the project goes private. And Datadef syncs diagrams, not prose; your written docs need their own review discipline.

• Embed diagrams in Markdown
• Embed diagrams in Backstage TechDocs
• Embed diagrams in Sphinx
• Docs checks in CI