Does Doxygen support Mermaid diagrams? Yes — since 1.17.0, and here is how to enable it

Does Doxygen support Mermaid diagrams?

Yes, natively, from version 1.17.0 onward.

The release added three commands and five configuration options. Here is the whole surface area in one place:

If you have used Doxygen's PlantUML support, the shape will be familiar: MERMAIDFILE_DIRS mirrors PLANTUMLFILE_DIRS and DOTFILE_DIRS, and MERMAID_PATH mirrors PLANTUML_JAR_PATH. This was deliberately modelled on the existing diagram integrations rather than invented from scratch.

Which Doxygen version do you need?

1.17.0 or later. Check before you debug anything else:

doxygen --version

The behaviour splits cleanly at that boundary, and knowing which side you are on saves a lot of wasted time:

The failure mode on an older version is quiet rather than loud: Doxygen does not recognise @mermaid, so it treats the block as ordinary comment text and your diagram source appears verbatim in the generated documentation. If you are seeing raw Mermaid code in your HTML output, check your version first.

How do you enable Mermaid in Doxygen?

Minimal working configuration, server-side rendering:

# Doxyfile
MERMAID_RENDER_MODE    = CLI
MERMAID_PATH           = /usr/local/bin
MERMAIDFILE_DIRS       = docs/diagrams

MERMAID_PATH points at the directory containing the mermaid-cli executable, which you install separately:

npm install -g @mermaid-js/mermaid-cli

For client-side rendering instead, leave MERMAID_RENDER_MODE at its default and Doxygen injects a script tag built from MERMAID_JS_URL. You need no local Mermaid install at all in that mode — the reader's browser does the work.

How do you write a Mermaid diagram in a Doxygen comment?

Wrap it in the block command, inside any documentation comment:

/**
 * @brief Parses an incoming frame.
 *
 * The parser is a small state machine:
 *
 * @mermaid
 * stateDiagram-v2
 *     [*] --> Idle
 *     Idle --> Header: byte received
 *     Header --> Payload: length valid
 *     Header --> Error: length invalid
 *     Payload --> Checksum: payload complete
 *     Checksum --> Idle: checksum ok
 *     Checksum --> Error: checksum bad
 *     Error --> Idle: reset()
 * @endmermaid
 */
int parse_frame(const uint8_t *buf, size_t len);

State machines, sequence diagrams, and flowcharts are where this earns its keep, because the diagram sits next to the function it describes and changes in the same commit.

If you prefer the backslash form of Doxygen commands, \mermaid and \endmermaid work identically — the @ and \ prefixes are interchangeable throughout Doxygen.

How do you include an external .mmd file?

For anything bigger than a few lines, keep the diagram in its own file and reference it:

/**
 * @brief Overall pipeline.
 *
 * @mermaidfile{ingest-pipeline.mmd}
 */

Then tell Doxygen where to look:

MERMAIDFILE_DIRS = docs/diagrams

This is the better default for anything you will maintain. A .mmd file is a first-class text file: it diffs cleanly in review, your editor can syntax-highlight it, and you can render it in any other Mermaid tool without first extracting it from a C comment. Diagrams buried in comment blocks tend to rot because nobody wants to edit a diagram through a *-prefixed margin.

What is the difference between the CLI and client-side render modes?

This is the configuration choice that matters most, and the trade-offs run in opposite directions.

The rule of thumb: if the documentation will ever be read offline, use CLI. Docs shipped inside a release tarball, published on an internal network, or opened from a local file:// path all fall into that category, and client-side mode degrades badly there — the diagram simply never appears.

Client-side mode makes sense for docs served over the public web where you want fast builds, and where a reader always has the CDN available.

Why does Doxygen load mermaid.js when you have no diagrams?

Because of a genuine wrinkle in 1.17.0 that is worth knowing before you upgrade: Doxygen includes the Mermaid JavaScript resources in the HTML output even for projects that contain no Mermaid diagrams at all. Since the default MERMAID_JS_URL points at a CDN, browsers reading the docs offline try to fetch a script they will never get, and the result is noticeable UI lag on every page.

The fix is the same switch as above:

MERMAID_RENDER_MODE = CLI

In CLI mode no Mermaid JavaScript is emitted, so the problem disappears whether or not you actually use Mermaid. Dimitri van Heesch pointed to this as the workaround when the behaviour was reported, and the issue is now closed — but the interaction is not obvious from the configuration documentation, so it catches people out. If you upgraded to 1.17.0 and your unrelated C++ docs suddenly feel sluggish, this is why.

Does Doxygen's Mermaid support render AWS architecture diagrams?

No — and this is the one limitation native support does not remove.

Mermaid's architecture-beta diagram type ships five built-in shapes (cloud, database, disk, internet, server). Cloud provider artwork comes from icon packs that the host application must register through Mermaid's registerIconPacks() API at initialisation. That is a JavaScript call, not a setting.

Doxygen gives you no hook for it in either mode:

• CLI mode shells out to mermaid-cli, which has no cloud icon packs bundled.
• Client-side mode injects a plain script tag. MERMAID_CONFIG_FILE takes a Mermaid configuration file, which has fields for themes and diagram defaults — and no field for registering icon packs, because registration is code rather than configuration.

So this renders as three empty labelled boxes:

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

The syntax is valid and every slug is real. Doxygen just has nothing to resolve them against. This is the same wall GitHub, Bitbucket, Notion, and Confluence all hit, for the same reason — see why cloud icons fail everywhere for the full explanation.

Is there any way to get cloud icons rendering in Doxygen?

There is one theoretical route, and it is worth knowing about mainly so you can decide against it.

In client-side mode you control MERMAID_JS_URL. Point it at your own Mermaid bundle — one that calls registerIconPacks() with the AWS pack before initialising — and the icons would in principle resolve, because you have replaced the script Doxygen loads with one that knows about the packs.

We have not tested this and would not recommend it as a documentation strategy. You would be maintaining a custom Mermaid build, hosting it somewhere your readers can reach, keeping it in step with Doxygen's expectations about how that script initialises, and accepting that the diagrams break for any offline reader. That is a lot of moving parts for a picture that does not change often.

How do you publish an AWS architecture diagram in Doxygen today?

Export it and include it as an image. Doxygen has had a perfectly good mechanism for this all along.

Author and validate the diagram first — this is the reference architecture from our validation guide, correct on every placement and every edge:

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

Export it as SVG or PNG, commit both halves, and reference the image:

/**
 * @page architecture System architecture
 *
 * @image html architecture.svg "Production AWS architecture" width=800px
 * @image latex architecture.pdf "Production AWS architecture"
 *
 * Diagram source: `docs/diagrams/architecture.mmd`
 */

Point IMAGE_PATH at the directory holding it:

IMAGE_PATH = docs/diagrams

Keeping the .mmd next to the exported image is what makes this maintainable rather than a screenshot graveyard — the source diffs in review, and the next person to change the architecture has something to edit. It is the same source-plus-image pattern that works on every other platform, which is the point: one workflow, no per-platform special cases.

What if you are stuck on Doxygen 1.16 or older?

Upgrading is the real answer, but if you cannot, three routes predate native support:

• ALIASES plus a custom HTML_HEADER. Define an alias that emits a <pre class="mermaid"> block and load mermaid.js from your header. This is what most pre-1.17 setups did, and community repositories such as tttapa/doxygen-mermaid and Notgnoshi/doxygen-mermaid package the pieces.
• FILTER_PATTERNS preprocessing. Run a script over your sources before Doxygen sees them, converting Mermaid blocks into whatever markup you want. More control, more to maintain.
• Pre-rendered images. The \image route above. It works on every Doxygen version ever released, needs no configuration beyond IMAGE_PATH, and is the only one of the three that handles cloud icons.

That last point is the practical case for images even after you upgrade: for cloud architecture specifically, the workflow you would use on 1.16 is the same one you use on 1.17.

Should you use Graphviz, PlantUML, or Mermaid?

Doxygen now supports three diagramming systems and they are not competing for the same work.

Keep Graphviz on for the graphs Doxygen derives from your source; nothing else does that job. Reach for Mermaid when you are explaining a design decision in prose and want a diagram in the same breath — its advantage over PlantUML is not expressiveness but reach, since the same .mmd renders on GitHub and GitLab without a toolchain. And for cloud architecture, author it where the icon packs live and include the export.