Markdown Mermaid Guide (2026) – Preview vs Export, Width Control, and Dependencies

A verified guide to Mermaid in md2word: why Mermaid is not part of CommonMark, how GitHub differs from export pipelines, how md2word renders Mermaid to PNG before export, how width control works, and what browser/CLI dependencies you need to check.

Author:md2word.comLast updated:2026-03-19

Mermaid looks like Markdown, but it is not Markdown core syntax.

That matters because Mermaid behavior changes depending on where you write it:

  • in GitHub Markdown
  • in a browser preview
  • in a Mermaid CLI pipeline
  • in a Word/PDF export workflow

If you only remember one thing, remember this:

Mermaid is a diagram language embedded in Markdown fences, not a CommonMark feature.

What Mermaid Is and What It Is Not

Mermaid is a text-based diagram tool. You write a fenced block, and a Mermaid renderer turns it into a diagram.

Example:

graph TD
  A[Input] --> B[Process]
  B --> C[Output]

That is useful, but it is not the same thing as standard Markdown lists, headings, or tables.

So if a guide says “Markdown supports Mermaid,” the more accurate version is:

  1. some Markdown environments support Mermaid fences
  2. Mermaid rendering is usually extension-based
  3. export behavior still depends on the toolchain

GitHub Support Is Not the Whole Story

GitHub Docs supports Mermaid in Markdown files, so diagrams can render nicely in repository docs.

That is convenient, but it can create a false sense of portability.

Why?

  1. GitHub is one renderer
  2. browser previews are another renderer
  3. export pipelines are a third layer

If a Mermaid diagram matters in a document that will leave GitHub, you should test the real target output instead of assuming preview parity.

How md2word Handles Mermaid

This section is based on the current repository implementation, not generic Mermaid lore.

Browser preview

In the editor and published page views, Mermaid is rendered in the browser with the mermaid package and output as SVG.

That means preview is fast and readable, but it is still a front-end render path.

Export path

Before Pandoc export, md2word scans fenced Mermaid blocks and pre-renders them to PNG images.

That gives you a more predictable Word/PDF result, but it also changes the nature of the content:

  1. the exported diagram is an image
  2. the image depends on the Mermaid render pipeline being available
  3. if local rendering is unavailable and remote fallback is enabled, md2word can use Kroki as a remote renderer
  4. if rendering still fails, md2word keeps the original Mermaid block instead of dropping content

That fallback is deliberate. It avoids silent data loss.

Once that happens, Mermaid stops behaving like source text and starts behaving more like an image asset. That is the right mental model when you are debugging width, layout, or final document fidelity.

Width Control

Width control is one of the most important practical differences between a demo diagram and an exportable diagram.

In md2word, you can annotate a Mermaid fence with width metadata, for example:

graph TD
  A --> B

The backend reads that width setting and writes it into the generated image link that Pandoc sees.

Useful details:

  1. a plain number is treated as a percentage
  2. values like px, cm, mm, in, and % are accepted
  3. if no width is provided, md2word falls back to its configured default width

This is a repo-level export feature, not Mermaid core syntax.

Local Dependencies and Optional Remote Fallback

Mermaid export is not just “run some JavaScript.”

In this project, the export pipeline can depend on:

  1. mmdc from Mermaid CLI
  2. a working Chrome or Chromium executable
  3. a valid Puppeteer runtime environment
  4. the selected backend mode
  5. an optional Kroki fallback when remote rendering is explicitly enabled

The backend resolution order is practical, not magical:

  1. MMDC_PATH
  2. local node_modules/.bin/mmdc
  3. PATH
  4. Windows global fallback

If the local diagram toolchain is not available, one of three things happens depending on configuration:

  1. md2word falls back to Kroki if remote fallback is explicitly enabled
  2. md2word keeps the original Mermaid fence if no image can be produced
  3. the export succeeds structurally, but not as a rendered diagram image

Security Mode Matters

Mermaid has security settings, and that matters for public documentation.

The practical takeaway is simple:

  1. strict is safer for public docs
  2. loose allows more HTML-like behavior and interaction
  3. sandboxed rendering changes what is allowed inside the diagram

If your diagram relies on interactive labels or HTML-like text tricks, test it under the same security mode you plan to deploy.

What Works Well

Mermaid is strongest when you use it for:

  1. simple flowcharts
  2. sequence diagrams
  3. state or process diagrams
  4. architecture sketches that benefit from source-controlled text

It is usually a poor fit when you need:

  1. perfect print typography
  2. pixel-level visual design
  3. guaranteed vector output in every export path
  4. highly interactive diagram behavior in a static Word/PDF document

Practical md2word Advice

1. Keep Mermaid in its own fenced block

Do not bury Mermaid inside another fragile structure unless you have tested that exact nesting.

2. Add width on diagrams that would otherwise be too wide

Long labels and wide diagrams are much more likely to export badly than short diagrams.

3. Expect PNG in export

If you need editable vector graphics, Mermaid-to-image export is the wrong assumption.

4. Treat preview as a preview, not a guarantee

If the diagram matters in the final document, export one real DOCX or PDF and inspect it.

5. Watch the dependency chain

If mmdc or Chrome is missing, the Mermaid page may still preview, but export may switch to Kroki or fall back to the original fenced block.

6. Be explicit about whether remote fallback is acceptable

For internal or privacy-sensitive documents, you may prefer a working local Mermaid toolchain over a remote render fallback.

Common Mistakes

1. Assuming Mermaid is part of standard Markdown

It is not.

2. Assuming GitHub behavior equals export behavior

It does not.

3. Depending on interactive Mermaid features in a static document

That usually breaks expectation more often than it helps.

4. Treating width control as a Mermaid universal

In md2word, width control is part of the export wrapper, not Mermaid itself.

5. Not checking whether the local or remote render path actually exists

If the renderer is missing, the export path may degrade to fallback behavior instead of producing the diagram you expected.

FAQ

Is Mermaid standard Markdown?

No. Mermaid is an embedded diagram language that many Markdown renderers support as an extension.

Why does Mermaid look fine in preview but not in PDF?

Preview and export use different rendering layers. In md2word, preview is browser-based while export renders Mermaid to PNG before Pandoc converts the document.

Can I control Mermaid width?

Yes, in md2word you can specify width in the fenced block attributes, and the export pipeline will carry that width into the generated image.

Is export always vector?

No. In this project, Mermaid is pre-rendered to PNG before export.

What should I test first?

One real Word or PDF export with the exact Mermaid diagram you plan to ship.

Further Reading

Changelog

  • 2026-03-18: Initial high-value release with verified guidance on CommonMark limits, GitHub support, md2word's PNG-based export path, width control, and browser/CLI dependencies.
  • 2026-03-19: Added clearer notes on Kroki fallback, local-vs-remote render paths, and treating exported Mermaid as an image asset for layout debugging.

Next steps: Explore Markdown Export Tips, Markdown Code Block Guide, Markdown Images Guide, Markdown LaTeX Guide, and Markdown Heading Guide.

Site Trust & Policies

About md2word.comContact md2word.comPrivacy PolicyTerms of Service