Mermaid diagram not rendering? Check these

Why does my Mermaid diagram show as code?

A Mermaid diagram is text inside a fenced code block. It only becomes a picture when the app showing the Markdown includes Mermaid and recognises that block. If you see the source instead of a diagram, either the block isn't marked the way the renderer expects, or the renderer can't draw it.

Work through the checks below in order. The first two cover most cases.

Is the block fenced and named mermaid?

The block must start with three backticks followed by the word mermaid, and end with three backticks on their own line:

```mermaid
flowchart LR
  A[README] --> B[Specification]
  B --> C[Decision record]
```

Common slips:

• A different language name. mermaid in lowercase is the identifier GitHub's diagram documentation uses. Variants such as mmd, Mermaid or graph may be shown as plain code.
• Indentation. A fence indented four spaces, or inside a list without the right indentation, can turn into an ordinary code block.
• A missing closing fence. Everything after it becomes code, including the rest of your document.

Does this app render Mermaid at all?

Mermaid support varies by app, and many viewers don't include it:

• GitHub renders Mermaid blocks in Markdown files, issues, pull requests and wikis.
• VS Code's built-in Markdown preview renders Mermaid blocks, according to its Markdown documentation.
• Plain-text editors such as TextEdit show the source, by design.
• Many online viewers show Mermaid as source. The free online Markdown viewer on this site is one of them; it says so under the tool.
• Quick Look extensions differ. QLMarkdown can render Mermaid when its Mermaid extension is enabled (see the QLMarkdown comparison).

If the app doesn't support Mermaid, the source is the correct result, not a bug. Open the file in an app that does.

Is the diagram itself valid?

When the renderer supports Mermaid but the syntax is wrong, you usually get an error message or a blank space instead of the code. Check:

• the diagram type on the first line (flowchart, sequenceDiagram, classDiagram, gantt…);
• arrows and brackets: -->, [label], {decision};
• quotes around labels that contain parentheses or other special characters.

Paste the block into the Mermaid Live Editor to see the exact error, then copy the corrected text back.

Is the diagram type newer than the renderer?

Mermaid adds diagram types and syntax over time. A diagram that renders in one app can fail in another that bundles an older Mermaid version. GitHub's documentation suggests a small block containing only info to show which Mermaid version it uses; some other renderers support the same trick. If an older version is the problem, use a more basic diagram type or syntax.

Does the renderer need the internet?

Some tools load the Mermaid library from the web when they render. Offline, the diagram can silently stay as code. QLMarkdown's README, for example, explains that its Mermaid and math libraries are either loaded from a CDN, which needs a connection, or embedded in the preview. If diagrams render at your desk but not on a train, look for an offline or "embed" option.

Aero Markdown bundles Mermaid inside the app, so diagrams render without a network connection.

Test with a known-good file

Download the Markdown rendering reference. Its README.md contains a working Mermaid flowchart next to a table, code, math and a local image. If that diagram renders and yours doesn't, the problem is in your block; if neither renders, it's the app. For reading diagrams once they work, see how to read Mermaid diagrams in Markdown.