Does Bitbucket render Mermaid diagrams? What works, what doesn't, and the workaround

Does Bitbucket render Mermaid diagrams natively?

No — not in any surface, and not on any hosting tier.

A fenced ```mermaid block in a README.md, a pull request description, a PR comment, or a wiki page is treated as an unknown language and displayed as a plain code block. There is no partial support, no preview mode, and no setting to turn on.

This is genuinely unusual in 2026. GitHub added native Mermaid rendering in 2022 and GitLab has had it for longer, so a diagram-as-code workflow that works fine on either of those hosts breaks the moment the same repository is mirrored to Bitbucket.

What is the actual status of native Mermaid support in Bitbucket?

Worth knowing precisely, because the answer people usually give — "it's on the roadmap" — is not accurate.

"Gathering Interest" is Atlassian's pre-triage state: it means the request needs more unique votes and comments before the team will even review it. It is not a queue position and it is not a commitment. BSERV-12548 has been sitting in it for six years.

The practical read: do not plan a documentation workflow around native Bitbucket Mermaid support arriving. Plan around it not arriving, and treat it as a bonus if it does.

What are your options for rendering Mermaid in Bitbucket?

Five routes exist. They are not equivalent, and the right one depends mostly on who needs to see the diagram.

The dividing line is the third column. Every route that renders Mermaid live inside Bitbucket does so with stock Mermaid, which means the five built-in shapes and nothing else. Only a pre-rendered image carries cloud provider artwork.

The second dividing line is who sees it. A browser extension renders the diagram for the person who installed it and for nobody else, which is fine for reading but useless for documentation — the whole point of a README diagram is that it works for the reviewer who has installed nothing.

Which Bitbucket Mermaid apps and extensions actually exist?

For Bitbucket Cloud, the options are Connect apps from the Atlassian Marketplace that add a file viewer or extend the markdown display:

• Mermaid Diagrams for Bitbucket (Plugio) — free, Cloud only, renders .md, .mmd, and .mermaid files in the repository browser with a built-in editor and dark mode. Version 3.1.0 shipped in May 2026.
• Markdown Plus for Bitbucket Cloud (Atly) — visualises Mermaid diagrams inside markdown files.
• File Renderers for Bitbucket (Eulo Labs) — renders .mmd and .mermaid files as interactive SVG.
• Mermaid Diagram Viewer (Vikeos) — free, renders .mmd and .mermaid in the repository browser.

For Bitbucket Data Center, markdown-extra-bitbucket is an open-source plugin that adds Mermaid, PlantUML, and KaTeX to the markdown renderer on versions 8.19 and above.

Browser extensions — the Chrome "Mermaid Diagrams for Bitbucket" extension and mermaid-previewer among them — inject a renderer into the page you are looking at.

Do these apps render AWS architecture diagrams?

No, and this is the part that catches teams out after they have already gone through app procurement.

Mermaid's architecture-beta diagram type ships five built-in shapes — cloud, database, disk, internet, server — and nothing else. Cloud provider artwork comes from icon packs the host application must register through registerIconPacks() before rendering. That registration is a property of the renderer, not the diagram.

Every Bitbucket rendering route above bundles stock Mermaid without cloud packs. So this diagram:

architecture-beta
group vpc(aws:virtual-private-cloud-vpc)[Production VPC]
service app(aws:arch-amazon-ec2)[App Server] in vpc
service db(aws:arch-amazon-rds)[Database] in vpc
app:R --> L:db

renders as three empty boxes with the right labels and no AWS artwork — after you install the app. The syntax is valid, the slugs are valid, and the renderer simply has nothing to resolve them against. If you are seeing placeholder boxes rather than raw code, the app is working and the icon pack is the missing piece.

The same constraint applies to hosted render-by-URL services, which is why mermaid.ink cannot fill the gap either — you do not control its renderer, so you cannot register the pack.

Should you commit SVG or PNG?

PNG, for Bitbucket specifically. This is the one place where the advice differs from GitHub.

Bitbucket's markdown renders SVG inconsistently. Self-contained SVG — where all artwork is embedded in the file — generally displays. SVG that references external images through <image> elements with no embedded data silently fails, showing nothing at all rather than an error. Diagram tools that export "linked" rather than "embedded" SVG hit this constantly.

Two practical rules if you use SVG anyway:

• Export with images embedded, never linked.
• Write relative paths without a leading slash — docs/architecture.svg, not /docs/architecture.svg. The leading slash is a known cause of images not displaying in Bitbucket markdown.

PNG has none of these failure modes and renders in every Bitbucket surface, including PR descriptions and wikis. Unless you specifically need the diagram to scale for print, export PNG and move on.

How do you publish an AWS architecture diagram in a Bitbucket README?

The workflow that survives all of the above, start to finish.

Author and validate the diagram first. This is the same reference architecture used in the diagram validation guide — every placement and every edge holds up, so it validates at zero rule violations:

architecture-beta
service users(aws:res-users-light)[Users]
service internet(aws:res-internet-alt1-light)[Internet]
group account(aws:aws-account)[AWS Account]
group region(aws:region)[us-east-1] in account
service s3(aws:arch-amazon-simple-storage-service)[Assets S3] in region
group vpc(aws:virtual-private-cloud-vpc)[VPC] in region
service igw(aws:res-amazon-vpc-internet-gateway)[Internet Gateway] in vpc
service alb(aws:res-elastic-load-balancing-application-load-balancer)[Load Balancer] in vpc
group pub(aws:public-subnet)[Public Subnet] in vpc
service nat(aws:res-amazon-vpc-nat-gateway)[NAT Gateway] in pub
group priv(aws:private-subnet)[Private Subnet] in vpc
service app(aws:arch-amazon-ec2)[App Server] in priv
group data(aws:private-subnet)[Data Subnet] in vpc
service db(aws:arch-amazon-rds)[RDS Database] in data
users:R --> L:internet
internet:R --> L:igw
igw:B --> T:alb
alb:B --> T:app
app:R --> L:db
app:B --> T:nat
nat:R --> T:igw
app:L --> R:s3

Then commit both halves — the picture and the text that produced it:

docs/
  architecture.mmd     <- the Mermaid source, reviewable in diffs
  architecture.png     <- the export, what Bitbucket displays
README.md

And reference the image with a relative path and no leading slash:

## Architecture

![Production AWS architecture](docs/architecture.png)

Source: [docs/architecture.mmd](docs/architecture.mmd)

Committing the .mmd alongside the image is what makes this better than pasting a screenshot. The source is plain text, so a change to the architecture shows up as a readable diff in the pull request, and the next person to edit the diagram has something to edit.

How do you show a Mermaid diagram in a Bitbucket pull request?

Same mechanism, since PR descriptions use the same renderer. Reference a committed image with markdown image syntax and it displays inline in the description.

What you cannot do is paste a fenced mermaid block into the description and expect a picture, and you cannot rely on a browser extension for this — the reviewer sees whatever their browser renders, so a diagram that depends on an extension is invisible to everyone who has not installed it.

The pattern that works well on architecture changes: include both the rendered image and the diff of the .mmd in the same pull request. Reviewers see what the architecture now looks like and exactly which lines changed to make it look that way, which is far more reviewable than a re-exported image on its own.

Can Bitbucket Pipelines render diagrams automatically?

Yes, and it is worth doing once diagrams change more than occasionally. mermaid-cli runs headless, so a pipeline step can regenerate images from source on every push and guarantee the committed picture matches the committed text.

# bitbucket-pipelines.yml
pipelines:
  default:
    - step:
        name: Render diagrams
        image: node:20
        script:
          - npm install -g @mermaid-js/mermaid-cli
          - mmdc -i docs/architecture.mmd -o docs/architecture.png
        artifacts:
          - docs/*.png

The caveat is the one from earlier: stock mermaid-cli has no cloud icon packs, so this works for flowcharts, sequence diagrams, and ER diagrams, and produces empty boxes for architecture-beta with aws: slugs. For cloud architecture, export from a renderer that has the packs registered and commit that image — the diagram changes far less often than the code around it, so a manual export on architecture changes is a reasonable trade.

A middle path that works well: run the pipeline step to render every non-cloud diagram automatically, and treat cloud architecture diagrams as a deliberate, reviewed artefact.

Should you install an app or just commit images?

Both, for different jobs — but if you only do one, commit images.

Install an app when your team writes a lot of core Mermaid (sequence diagrams for API flows, ER diagrams for schema, state charts) and wants to read it in the browser without a build step. That is a real quality-of-life gain and the free options make it cheap to try.

Commit images when the diagram is documentation — something a new engineer, an auditor, or someone outside the workspace needs to see. An image has no dependency on an app remaining installed, a licence remaining active, or a viewer's browser configuration. It also survives the repository being mirrored, archived, or exported.

For AWS, Azure, and GCP architecture diagrams the decision is made for you, because no app renders the icons. The workflow is: author and validate in the editor, export PNG, commit both files.

What changes if Bitbucket adds native support?

Nothing about the recommended workflow, which is the point of choosing it.

If BCLOUD-21675 ships, fenced mermaid blocks start rendering in Bitbucket markdown and core diagrams get easier — a genuine improvement worth taking. Cloud architecture diagrams will still need exported images, because native support means stock Mermaid, and stock Mermaid does not register the AWS icon pack. GitHub is the proof: it has rendered Mermaid natively since 2022, and architecture-beta diagrams with aws: slugs still come through with broken icons there today.

That is the durable reason to keep the source-plus-image pattern regardless of what Atlassian ships. If you are still writing the diagram itself, start with how to draw AWS architecture diagrams in Mermaid, and check it against the common AWS architecture mistakes before you export.