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.

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.