Docs & Code Guide

Embed a diagram in Bitbucket: the image-by-URL path that survives HTML stripping

Bitbucket Cloud is the strictest of the big three code hosts about what a README may contain. Raw HTML is stripped wholesale from rendered markdown, and native Mermaid support in .md files still has not shipped despite one of the longest-running feature requests in the tracker. What remains is enough: a markdown image pointing at a live URL. Here is exactly what works, what does not, and the two quirks worth knowing.

Try it free
6 min readFor teams hosting on Bitbucket Cloud with diagrams going stale in the README

See it as a diagram

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

163/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Bitbucket Cloud strips raw HTML entirely

Where GitHub sanitizes HTML down to an allowlist, Bitbucket Cloud removes it altogether. An iframe, a picture element, even a plain div in your README markdown simply does not appear in the rendered page. There is no interactive embed route and no theme-switching markup: the rendered README is markdown constructs only.

That narrows the decision usefully. If you want a diagram in a Bitbucket README at all, it is either a committed image file, which goes stale until someone regenerates and commits it, or a markdown image pointing at a URL that re-renders when the diagram changes.

The markdown image that works

Bitbucket renders standard markdown image syntax in READMEs, other .md files, and pull request descriptions. Point it at a live endpoint and the README stays current without commits: Datadef serves the image with a five minute cache lifetime and an ETag tied to the last edit, so an edited diagram shows up within minutes wherever the URL is rendered.

The endpoint accepts sizing parameters when the default 1600x1000 render at 2x does not fit: format png or jpeg, width 600 to 4000, height 400 to 4000, scale 1 to 3.

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

<!-- Works in README.md and pull request descriptions.
     Sized variant: -->
![System architecture](https://datadef.io/api/embed/my-platform-a1b2c3d4?width=2000&height=1200&scale=2)

Mermaid in Bitbucket: .mmd files yes, README no

Bitbucket Cloud does not render Mermaid fenced blocks inside markdown files, so the pattern that works in a GitHub or GitLab README shows up here as a literal code block. The feature request (BCLOUD-21675) has been open for years without shipping.

What Bitbucket does render is standalone .mmd files: open one in the source browser and it draws as a diagram. That is useful for a diagram someone browses to deliberately, and useless for the README itself, which cannot include a .mmd file inline. Marketplace apps and browser extensions exist that render Mermaid blocks client-side, but they only work for readers who installed them, which a README cannot assume.

The wiki is its own repository

A Bitbucket wiki, once enabled in repository settings, lives in a separate repo you can clone and push independently of the code. Its pages have their own markup rules and render markdown images by URL the same way the README does, so the identical line keeps a wiki architecture page current.

Because the wiki repo does not ride the code review flow, its prose drifts even faster than a README. A live image removes the stale-screenshot half of that problem; the prose half needs process, which is its own subject in keep your README in sync with code.

Keeping the diagram current, and the honest limits

The live URL means nobody re-exports and re-uploads a PNG. It does not mean the diagram edits itself. When the architecture changes, someone updates the diagram in Datadef, or an AI agent does: the Datadef MCP server (registry name io.datadef/mcp) lets an agent like Claude Code read the repository and update the diagram to match, invoked after a merge, from CI, or on request. Datadef does not watch your repository; nothing regenerates until an agent call or CI command asks for it. An API key from the paid plans authorizes the connection.

The other limit is visibility. The embed URL exists only while the source project is shared public. Private diagram, no embed: the URL 404s. Confidential architectures on Bitbucket are better served by a committed export regenerated in CI, accepting staleness between runs.

Quick decision

Bitbucket README: image by URL is the only live option. Small flow you want versioned with the code: a committed .mmd file readers browse to. Interactive pan and zoom: link out to the diagram page, since no iframe will ever render here.

FAQ

How do I embed a diagram in a Bitbucket README?

Use standard markdown image syntax with an external URL, for example ![Architecture](https://datadef.io/api/embed/your-slug). Bitbucket Cloud strips all raw HTML from rendered markdown, so images are the only embed form; pointing one at a live URL keeps the README current without commits.

Does Bitbucket support Mermaid diagrams in markdown?

Not in .md files. Mermaid fenced blocks in a Bitbucket Cloud README render as plain code. Standalone .mmd files do render as diagrams when opened in the source browser, and marketplace apps or browser extensions can render Mermaid client-side for readers who install them.

Can I put an iframe in a Bitbucket README or wiki?

No. Bitbucket Cloud removes raw HTML from rendered markdown entirely, including iframes. For an interactive diagram, link readers to the diagram page instead and keep an image in the README.

How does the Bitbucket wiki handle images?

The wiki lives in its own repository, separate from the code, and renders markdown images by URL the same way the README does. The same live image line works on wiki pages, and you can clone and push the wiki repo independently.

How quickly does an embedded diagram update in Bitbucket?

Within minutes of an edit. The image is served with a five minute cache lifetime, so browsers re-validate on that schedule. The first render after an edit takes a few extra seconds while it is produced, then it is cached.