How do you render and embed Mermaid AWS architecture diagrams in GitHub, Notion, and Confluence?

Does GitHub render Mermaid architecture-beta diagrams with AWS icons?

No — not the cloud icons. GitHub renders Mermaid inside fenced code blocks marked ```mermaid, and it supports the core diagram types: flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram, gantt, and a handful of others. A plain architecture-beta diagram that uses only the built-in shapes (internet, server, database, cloud, disk) will mostly render.

The moment you reference an external icon pack — any aws:, azure:, or gcp: slug — GitHub's bundled Mermaid configuration has no icons registered under those names, so each one fails to load. You get the diagram skeleton with empty boxes where the icons should be.

architecture-beta
    service internet(internet)[Internet]
    group vpc(aws:virtual-private-cloud-vpc)[VPC]
        service ec2(aws:ec2-instance-contents)[Web Server] in vpc
    internet:R <--> L:ec2

In LatixEngine that renders with the real VPC and EC2 icons. On GitHub, the internet icon shows (it is built in) but the two aws: icons do not. This is why the rest of this post exists: you publish the rendered artifact, not the raw source.

Why do cloud-icon Mermaid diagrams fail to render when plain flowcharts work?

Because icon packs are not part of Mermaid's core. Mermaid ships the diagram engine and a tiny set of built-in shapes. Everything else — the 1698 AWS, Azure, and GCP icons that make an architecture diagram look like an architecture diagram — is registered separately through Mermaid's registerIconPacks API at initialization time.

Every renderer makes its own decision about which packs to register. GitHub, GitLab, and Notion all run their own server-side or client-side Mermaid build with no cloud icon packs registered, because shipping thousands of third-party icons by default is a size and licensing decision they have not made. LatixEngine, by contrast, preregisters all three provider packs, which is why the same source renders there and nowhere else.

So the failure is not a bug in your diagram or in Mermaid. It is a configuration gap between the renderer that has the icons (LatixEngine) and the renderer that publishes your docs (GitHub et al). You bridge that gap by exporting the rendered diagram as an image.

How do you embed a Mermaid AWS diagram in a GitHub README?

Author the diagram in LatixEngine, export it as SVG, commit the SVG into the repo, and reference it with a standard image tag. Keep the .mmd source next to it so the diagram stays diffable and editable.

The directory layout that works well:

docs/
  architecture/
    vpc-web-app.mmd      # Mermaid source — the source of truth
    vpc-web-app.svg      # exported from LatixEngine — what renders

Then in your README.md or any markdown file:

![VPC web application architecture](docs/architecture/vpc-web-app.svg)

The SVG renders identically for everyone viewing the repo on github.com, in a pull request diff, and in any markdown previewer. When the architecture changes, you edit the .mmd, re-export the SVG, and commit both — reviewers see the source diff and the updated picture in the same change.

How do you add a Mermaid architecture diagram to Notion?

Notion has a Mermaid preview built into its code block — type /code, choose the Mermaid language, and toggle "Preview". It handles flowcharts and sequence diagrams, but it does not register cloud icon packs, so an architecture-beta AWS diagram shows broken icon placeholders.

The workflow that works in Notion:

• Export the diagram as PNG or SVG from LatixEngine. PNG is the safest paste target in Notion.
• Drag the image into the page, or use /image and upload it.
• Optionally add a collapsed toggle block underneath titled "Mermaid source" and paste the .mmd text inside, so the editable source lives next to the rendered image without cluttering the page.

This gives readers the picture immediately and keeps the source one click away for whoever maintains the diagram.

Does Confluence support Mermaid architecture-beta?

Not natively, and not reliably even with plugins. Confluence has no built-in Mermaid support. Teams add it through third-party macros from the Atlassian Marketplace, but those macros bundle their own Mermaid build, and none of them ship the AWS, Azure, or GCP icon packs. So even where live Mermaid rendering works for flowcharts, your architecture diagram's cloud icons will not appear.

On Confluence, skip live rendering for architecture diagrams entirely:

• Export PNG from LatixEngine (Confluence's image handling is most predictable with PNG).
• Insert it with the standard image/attachment tool.
• Attach the .mmd file to the page as well, so the source travels with the page for the next editor.

If your team standardizes on one Mermaid macro for flowcharts, that is fine — just keep architecture-beta diagrams as exported images, because the icon packs will never be present in the macro's build.

Should you export Mermaid diagrams as SVG or PNG?

Both come straight out of the LatixEngine editor toolbar. The choice is about the destination, not the diagram.

The rule of thumb: SVG anywhere it is supported, PNG everywhere else. SVG keeps the diagram sharp at any zoom and stays small; PNG is the universal fallback for surfaces that strip or mishandle vector images.

How do you keep the diagram and its Mermaid source in sync?

Commit them together, named the same, in the same directory. The anti-pattern is exporting an image once, pasting it into a doc, and losing the source — six months later nobody can edit the diagram and it gets redrawn from scratch.

The pattern that prevents drift:

• Name the pair identically: payments-flow.mmd and payments-flow.svg.
• Store both in the repo (or attach both to the wiki page) so they travel together.
• Change them in one commit: edit the .mmd in LatixEngine, re-export the image, commit both.
• For repos that publish docs in CI, add a check that greps the Mermaid source for (aws|azure|gcp):[a-z0-9-]+ slugs and validates them against the catalog at latixengine.com/icons.json, failing the build on any unknown slug. That is the same validation LatixEngine runs against its own docs.

This keeps the rendered picture and the editable text as a single reviewable unit, so the diagram never rots away from the architecture it describes.

Does Bitbucket render Mermaid diagrams?

No — Bitbucket Cloud does not render Mermaid in markdown, READMEs, or pull requests the way GitHub and GitLab do. Native support has been an open request for years, so a fenced mermaid block shows up as raw code rather than a diagram. You can add rendering with a browser extension or an Atlassian Marketplace app ("Mermaid Diagrams for Bitbucket"), and Bitbucket Data Center has third-party plugins that extend the markdown renderer.

Those add-ons render core Mermaid, though — none of them register the AWS icon packs, so an architecture-beta diagram full of aws: slugs still comes through with broken placeholder icons even after you install one. The dependable, zero-dependency approach is the same one that works everywhere else: author and validate the diagram in the LatixEngine editor, export an SVG, and commit it next to the .mmd source so every teammate sees the same picture whether or not they have an extension installed.

Bitbucket is the platform this trips up most often, so it has its own deep dive: does Bitbucket render Mermaid diagrams? covers the current Atlassian ticket status, every app and extension compared, the pull request and Pipelines workflows, and why PNG is the safer export format there than SVG.

Can mermaid.ink render a Mermaid AWS diagram?

mermaid.ink is a hosted rendering service: you encode a diagram into the URL and it returns an image, which is handy when you need to embed a diagram somewhere that accepts an image URL but not a code block. It runs stock Mermaid, so plain flowcharts and sequence diagrams come back fine.

AWS diagrams are the exception. architecture-beta only shows cloud icons when the renderer has the pack registered through registerIconPacks() — and on a hosted service you do not control the renderer, so there is no way to register the AWS icons. Your diagram returns with the five built-in shapes and broken placeholders where the aws: icons should be. The same limitation applies to any render-by-URL endpoint. When you need an image URL for an AWS diagram, export the SVG or PNG from LatixEngine — where all 1698 cloud icons are already registered — and host that image instead.

How do you add a Mermaid AWS diagram to Doxygen?

Doxygen supports Mermaid natively as of 1.17.0, released 30 April 2026. That version added the @mermaid/@endmermaid block commands, @mermaidfile for external .mmd files, and five configuration options — MERMAID_RENDER_MODE, MERMAID_PATH, MERMAID_JS_URL, MERMAID_CONFIG_FILE and MERMAIDFILE_DIRS. On 1.16.x and older there are no Mermaid commands at all, and the pre-1.17 community routes apply instead: a custom HTML_HEADER that loads mermaid.js plus a Doxyfile ALIAS, a FILTER_PATTERNS preprocessing script, or a pre-rendered image.

For AWS architecture diagrams even native support hits the familiar wall: neither render mode registers cloud icon packs, so the aws: icons never appear. The clean path is to export an SVG from LatixEngine and include it with Doxygen's \image command (or inside an \htmlonly block). The diagram then renders identically in the generated docs, with no client-side JavaScript and no icon-pack setup to maintain. Full detail — configuration, the CLI vs client-side render modes, and the CDN gotcha in 1.17.0 — is in the Doxygen Mermaid deep dive.

Which platforms render Mermaid cloud diagrams natively today?

Here is the honest state of play for architecture-beta with AWS/Azure/GCP icon packs, as opposed to plain flowcharts. "Native" means the cloud icons render from raw Mermaid source with no image export.

The pattern is consistent: every general-purpose platform renders core Mermaid but none register the cloud icon packs. So the portable answer for AWS architecture diagrams is always the same — author and validate in LatixEngine, export SVG (or PNG where SVG is not supported), and commit the image next to the .mmd source.

If you are still writing the diagram itself, start with our guide on how to draw AWS architecture diagrams in Mermaid. And if you want an LLM to generate the source for you, see how to get ChatGPT or Claude to produce valid Mermaid AWS diagrams — then bring the output back here to publish it.