Embed a diagram in an Azure DevOps wiki: what its markdown allows and where Mermaid stops

Standard markdown images render in wiki pages, and external URLs are fetched at view time, which is what makes a live diagram possible: point the image at an endpoint that re-renders on change and the wiki page follows without edits.

Azure DevOps adds its own sizing notation that most platforms lack: append =WIDTHxHEIGHT inside the parentheses, after the URL, to set display dimensions. Height is optional (=600x works too). This controls display size only; for a sharper source on wide pages, the Datadef endpoint also takes render parameters for width, height, and scale.

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

<!-- Sharper render for a full-width page section -->
![Platform architecture](https://datadef.io/api/embed/my-platform-a1b2c3d4?width=2400&height=1400 =1100x)

Unlike GitHub, the ADO wiki does accept some raw HTML in markdown: basic formatting tags survive. But iframes are restricted to an allowlist of video providers, YouTube and Microsoft Streams among them, so an iframe pointing at an arbitrary interactive diagram page will not render. The interactive form of an embed is effectively unavailable in the wiki.

The practical pattern is the one the image supports: a live image in the page, with the image linked to the full diagram for readers who want to pan and zoom there. Wrap the image markdown in a link the usual markdown way and both needs are met.

The wiki renders Mermaid through its own fence syntax: a line with ::: mermaid, the diagram source, and a closing :::. Two caveats keep tripping teams. First, the wiki runs Mermaid 8.13.9, several major versions behind current, so syntax copied from recent Mermaid documentation often fails to render. Diagram types in experimental mode at that version, entity relationship and git graph among them, are not included, and the docs steer you to graph rather than flowchart syntax.

Second, the general Mermaid ceiling applies with the older version pulling it lower: generated layout communicates well up to roughly 20 nodes and degrades past that. Sequence diagrams of a single flow are the sweet spot. A full platform view with zones and detail belongs in a deliberately laid out diagram behind a live image URL.

Azure DevOps has two wiki modes and the difference matters for diagram workflows. A provisioned project wiki is edited in the web UI and stored in a repo Azure DevOps manages for you. A code wiki publishes a folder of markdown from a repository you own, which means wiki pages ride your normal PR flow: branch, review, merge, published.

For a live diagram the markdown is identical in both. The code wiki pairs better with automation, because the same pipeline that merges a change to the system can also carry the reminder, or the agent call, that updates the diagram the page shows.

The [[_TOC_]] macro renders a table of contents from the page headings, which suits a long architecture page: one section per subsystem, each anchored by a heading, each carrying its own diagram where needed.

Keeping those diagrams true is the real work. Datadef ships an MCP server (registry name io.datadef/mcp) so a connected agent can update the diagram from what it reads in the repository, invoked after a merge, from a scheduled pipeline, or on request. Datadef does not watch repositories; regeneration happens when an agent call or CI command asks for it. The agent authenticates with a key that paid plans carry. The embed itself requires the project to be shared public, and turns into a 404 if the project goes private. The wiki-wide version of this practice is covered in keep your internal wiki in sync.

• Embed diagrams in Markdown
• Embed diagrams in SharePoint
• Embed diagrams in Confluence
• Keep your internal wiki in sync