Mermaid diagrams in Markdown

To add a Mermaid diagram in Markdown, write the diagram as text inside a fenced code block whose info string is mermaid. A supporting renderer reads the Mermaid syntax and draws a flowchart, sequence diagram, or other chart from it. Mermaid is not Markdown syntax; it is a diagramming feature that supporting renderers add on top of the code fence.

Mermaid diagrams in Markdown syntax reference

Mermaid diagrams in Markdown key facts

• Add a diagram by putting Mermaid text inside a fenced code block with the mermaid info string.
• The first keyword in the block selects the diagram type, such as flowchart, sequenceDiagram, or pie.
• Mermaid is not part of any core Markdown specification, so it is a renderer feature layered on the standard code fence.
• GitHub has rendered Mermaid natively since February 2022 in files, issues, pull requests, wikis, and discussions.
• GitLab, Notion, and Obsidian also render Mermaid natively, while plain CommonMark, MultiMarkdown, and Markdown Extra show the block as code.
• The info string must be exactly mermaid, with no capitalization or trailing space, or the block renders as plain code.

Treat Mermaid as executable diagram source

Mermaid code is usually stored inside a fenced block labelled mermaid, but the Markdown renderer must load a compatible Mermaid version to turn it into a diagram. A renderer without Mermaid support shows a code block instead.

Keep the diagram source readable and provide surrounding text that communicates the important conclusion. This gives readers a fallback when scripts are disabled or an export format cannot render the diagram. Mermaid syntax changes across releases, so record the tested version for complex diagrams and avoid assuming that every GitHub, editor, or static-site integration supports the same diagram types.

Basic syntax

Open a fenced code block, add mermaid as the info string, write the diagram definition, then close the fence. On a supporting renderer, the block is replaced with a drawn diagram instead of code.

Markdown

```mermaid
flowchart TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Ship it]
    B -->|No| D[Debug]
    D --> B
```

Rendered output

flowchart TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Ship it]
    B -->|No| D[Debug]
    D --> B

HTML output

<pre class="mermaid">
flowchart TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Ship it]
    B -->|No| D[Debug]
    D --> B
</pre>

The exact HTML depends on the platform. GitHub, for example, emits a progressive <pre> element and then injects an iframe that runs Mermaid.js in the browser and swaps in an SVG. On a renderer without Mermaid support, the same block falls back to a normal syntax-highlighted code block showing the literal text.

Diagram types

Mermaid supports many diagram types. The first keyword in the block selects the type. Below are a few common ones.

Flowchart

Flowcharts use flowchart (or the older graph) followed by a direction such as TD (top-down) or LR (left-right).

Markdown

```mermaid
flowchart LR
    A[Write] --> B[Preview] --> C[Publish]
```

Rendered output

flowchart LR
    A[Write] --> B[Preview] --> C[Publish]

Sequence diagram

Sequence diagrams show messages passing between participants over time.

Markdown

```mermaid
sequenceDiagram
    User->>App: Open document
    App->>Renderer: Parse Markdown
    Renderer-->>User: Show preview
```

Rendered output

sequenceDiagram
    User->>App: Open document
    App->>Renderer: Parse Markdown
    Renderer-->>User: Show preview

Pie chart

A pie chart is declared with pie and a set of labeled values.

Markdown

```mermaid
pie title Editor time
    "Writing" : 60
    "Editing" : 30
    "Previewing" : 10
```

Rendered output

pie title Editor time
    "Writing" : 60
    "Editing" : 30
    "Previewing" : 10

Info string requirement

The block only renders as a diagram when the info string is exactly mermaid, written directly after the opening fence with no space. A misspelled or capitalized info string, or an extra space, makes the renderer treat the content as a plain code block.

Markdown

```Mermaid
flowchart TD
    A --> B
```

Rendered output

flowchart TD
    A --> B

Flavor differences

Mermaid is not defined by any core Markdown specification. It is a rendering feature layered on the standard fenced code block. GitHub Flavored Markdown, for instance, formally adds exactly five extensions to CommonMark, and Mermaid rendering is not one of them; it is a GitHub renderer behavior added in February 2022.

Mermaid source commonly uses a fenced code block. Renderers that recognise the fence but lack Mermaid support usually show code; incompatible or older parsers may behave differently. GitHub renders Mermaid natively. Pandoc needs an external filter to turn ```mermaid blocks into images, so treat bare Pandoc as unsupported and verify against your specific filter setup. CommonMark, MultiMarkdown, and classic Markdown Extra show the literal Mermaid text as a code block.

Other platforms (GitLab, Notion, Obsidian)

• GitLab: renders Mermaid natively in issues, merge request descriptions, comments, and wikis.
• Notion: supports Mermaid as a code block language. Selecting the Mermaid language renders the diagram inline.
• Obsidian: renders Mermaid natively in reading view and live preview with no plugin required.

For the full comparison of how flavors differ across all elements, see Markdown flavors.

How Markdific renders it

Markdific renders Mermaid diagrams. A fenced code block with the mermaid info string is drawn as a diagram rather than shown as code.

Common diagram types, including flowcharts, sequence diagrams, and pie charts, are supported through Mermaid's own syntax.

Try it in the Markdific online editor.

Common mistakes and gotchas

• Wrong info string. Only mermaid triggers diagram rendering. Mermaid, mmd, or a trailing space makes it a plain code block.
• Assuming universal support. Mermaid renders only on supporting platforms. In a plain CommonMark renderer, the block shows raw text.
• Syntax errors in the diagram. A malformed diagram definition produces a Mermaid error box or no diagram, not a Markdown error. Validate the diagram syntax separately.
• Indenting the fence. Indenting the opening ```mermaid by four or more spaces can turn it into an indented code block, so keep the fence at the left margin or at its list-item indent.
• Mixing tabs and spaces inside the diagram. Mermaid is sensitive to its own indentation and node syntax. Keep it consistent.
• Expecting identical output everywhere. Themes, fonts, and Mermaid versions differ across platforms, so the same diagram can look different on GitHub, GitLab, and Obsidian.

Best practices

• Use the exact mermaid info string, directly after the opening fence.
• Keep diagrams small and focused. Split a large diagram into several rather than one dense chart.
• Declare an explicit direction (TD or LR) so layout is predictable.
• Add a fallback caption or short description near the diagram for readers on platforms that do not render Mermaid.
• Validate complex diagrams in a live Mermaid editor before committing them.
• Remember that Mermaid is a renderer feature, so do not rely on it in documents meant to be portable across different Markdown renderers.

HTML equivalent

Markdown Mermaid blocks compile to renderer-specific HTML. A common pattern places the raw diagram text inside a <pre class="mermaid"> element, which the Mermaid.js script then replaces with an inline SVG in the browser.

Markdown

```mermaid
flowchart TD
    A[Start] --> B[End]
```

HTML output

<pre class="mermaid">
flowchart TD
    A[Start] --> B[End]
</pre>

FAQ

How do you add a Mermaid diagram in Markdown? Open a fenced code block, use mermaid as the info string, write the Mermaid diagram definition, then close the fence. On a supporting renderer, the block is drawn as a diagram.

Does GitHub render Mermaid diagrams? Yes. GitHub has rendered Mermaid natively since February 2022 in Markdown files, issues, pull requests, wikis, and discussions, using fenced code blocks tagged with the mermaid info string.

Is Mermaid part of the Markdown specification? No. Mermaid is a diagramming feature layered on the standard fenced code block. It is not defined by CommonMark and is not one of the five formal GitHub Flavored Markdown extensions.

Which platforms render Mermaid? GitHub, GitLab, Notion, and Obsidian render Mermaid natively. Pandoc needs an external filter such as mermaid-filter. Plain CommonMark, MultiMarkdown, and classic Markdown Extra show the block as code.

What diagram types does Mermaid support? Mermaid supports flowcharts, sequence diagrams, class diagrams, state diagrams, entity relationship diagrams, Gantt charts, pie charts, and user journey maps, among others. The first keyword in the block selects the type.

Why is my Mermaid block showing as code instead of a diagram? Either the platform does not render Mermaid, or the info string is not exactly mermaid. Check the spelling and capitalization and confirm the target renderer supports Mermaid.

Can Pandoc convert Mermaid diagrams? Not on its own. Pandoc treats ```mermaid as a plain code block unless you add a filter such as mermaid-filter, which renders the diagram to an image during conversion.

How do you make a flowchart in Markdown? Open a mermaid code block, start it with flowchart and a direction such as TD or LR, then define nodes and arrows, for example A[Start] --> B[End]. On a supporting renderer the block is drawn as a flowchart.

Does GitLab render Mermaid diagrams? Yes. GitLab renders Mermaid natively in issues, merge request descriptions, comments, and wikis, using the same mermaid fenced code block.

Can you set the direction of a Mermaid flowchart? Yes. Add a direction keyword after flowchart or graph, such as TD for top-down, LR for left-right, RL for right-left, or BT for bottom-top. Declaring one makes the layout predictable.

Why does my Mermaid diagram look different on GitHub and Obsidian? Because themes, fonts, and Mermaid versions differ across platforms. The same diagram definition can render with different colors, spacing, and styling depending on the tool, even though the structure stays the same.

Sources and compatibility references

• Mermaid documentation
• GitHub: creating diagrams

Use these primary references for syntax rules. Renderer behaviour can still vary by version and configuration, so preview important documents in their final destination.

Related pages

• Markdown documentation hub
• Fenced code blocks
• Syntax highlighting
• LaTeX math in Markdown
• Images in Markdown
• Markdown flavors compared