Mermaid Diagrams

With the mermaid language ID, you can render flowcharts and other diagrams in your content by writing Mermaid markup inside of a codeblock.

Syntax #

With Attributes #

```mermaid { [.class [.class]] [#id] [as_figure=(true|false)] [container="container"] }
[%%{ <InitDirective> }%%]

<MermaidMarkup>
```

With Data #

```mermaid
---
as_figure: false
caption: caption
caption_position: (top|bottom)
class: class
container: pre
id: id
---

[%%{ <InitDirective> }%%]

<MermaidMarkup>
```

Examples #

1. Flowchart #

Markdown Input
```mermaid
flowchart LR
  a --> b & c--> d
```
HTML Output
<pre class="mermaid">
flowchart LR
  a --> b & c--> d
</pre>
Rendered Output
flowchart LR
  a --> b & c--> d

2. Pie Chart #

Markdown Input
```mermaid
pie
  title Monsters the Author has Cuddled by Kind
  "Eldritch" : 66
  "Ravenous" : 114
  "Draconic" : 36
```
HTML Output
<pre class="mermaid">
pie
  title Monsters the Author has Cuddled by Kind
  "Eldritch" : 66
  "Ravenous" : 114
  "Draconic" : 36
</pre>
Rendered Output
pie
  title Monsters the Author has Cuddled by Kind
  "Eldritch" : 66
  "Ravenous" : 114
  "Draconic" : 36

3. With Initialize Directive #

Markdown Input
```mermaid
%%{
  init: {
    "theme":    "forest",
    "logLevel": 1
  }
}%%

flowchart LR
  a --> b & c--> d
```
HTML Output
<pre class="mermaid">
%%{
  init: {
    "theme":    "forest",
    "logLevel": 1
  }
}%%

flowchart LR
  a --> b & c--> d
</pre>
Rendered Output
%%{
  init: {
    "theme":    "forest",
    "logLevel": 1
  }
}%%

flowchart LR
  a --> b & c--> d

4. As Figure #

Markdown Input
```mermaid
---
caption: An example flowchart
---
flowchart LR
  a --> b & c--> d
```
HTML Output
<figure>
  <pre class="mermaid">
flowchart LR
  a --> b & c--> d
  </pre>
  <figcaption>
    An example flowchart
  </figcaption>
</figure>
Rendered Output
flowchart LR
  a --> b & c--> d
An example flowchart

Attributes #

class #

Specify any additional classes to add to the Mermaid-containing element. By default, the Mermaid code is placed in its container element that has the mermaid class.

If as_figure is true, the classes are added to both the figure and the container element.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

id #

Specify a page-unique ID to use as the id attribute of the Mermaid-containing element. If as_figure is true, the ID is added to the figure instead.

Specify the ID as a bare string without any spaces and with a # prefix, like #my-id

Required: false
Type: String

as_figure #

Specify whether to render the mermaid diagram inside a <figure> element. When this value is true, the mermaid diagram is added inside a figure and the id and class both apply to that figure. The class is also inherited on the container for the diagram.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

container #

Specify an alternate container element for the Mermaid-containing element. By default, the Mermaid code is placed in a pre element. The value you specify for this attribute is used as the open and closing tag name for the container element. For example, if you specify div, the Mermaid code is placed in a div instead of pre.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

YAML Options #

as_figure #

Specify whether to render the mermaid diagram inside a <figure> element. When this value is true, the mermaid diagram is added inside a figure and the id and class both apply to that figure. The class is also inherited on the container for the diagram.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

caption #

Specify Markdown to use as the caption for the figure element. If this value is set, the Mermaid diagram is rendered inside a figure element even if as_figure isn’t set to true.

The caption’s Markdown is rendered as a block without wrapping <p> tags inside a <figcaption> element. By default, it’s added beneath the diagram.

You can use the caption_position option to render the caption above the Mermaid diagram in the figure.

To write a multiline string, specify either | or > after the key. Add a - to trim the final newline. For example:

caption: |
  This is a multiline entry. The line endings are respected,
  meaning this would render as two paragraphs.

  This is the second paragraph. Because there's no `-`,
  This would include a trailing newline.  
caption: |-
 This multiline entry trims the final newline. 
caption: >
  This entry replaces the newlines, except for the
  last one, with spaces. With the `-`, that final
  newline would be trimmed too.

This value is rendered as a block of Markdown. If there’s only one line, that line is wrapped in <p> tags.

RendersMarkdown: true
Required: false
Type: String

caption_position #

Specify either top or bottom to render the figure’s caption above or below the Mermaid diagram. The default value is bottom. This option is ignored if caption isn’t set or is empty.

Required: false
Type: Enum
ValidValues:
- top
- bottom

class #

Specify any additional classes to add to the Mermaid-containing element. By default, the Mermaid code is placed in its container element that has the mermaid class.

If as_figure is true or caption is set, the classes are added to both the figure and the container element.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

container #

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

id #

Specify a page-unique ID to use as the id attribute of the Mermaid-containing element. If as_figure is true or caption is set, the ID is added to the figure instead.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

Definition #

There are two components to the definition syntax inside the codeblock: the Mermaid intialize directive and the Mermaid syntax.

The only required component is the actual Mermaid diagram syntax. This defines the diagram that Mermaid renders. For more information about creating diagrams with Mermaid, see the Mermaid documentation.

Initialize Directive #

Immediately before the diagram syntax, you can specify an initialize directive for Mermaid. This overrides the site’s Mermaid configuration for this diagram only.

You can add the initialize directive on a single line:

%%{ init:{ <settings> } }

Or multiline:

%%{
  init: {
    <settings>
  }
}%%

For more information on the initialize directive, see “Directives” in Mermaid’s documentation.

Mermaid Markup #

The diagram syntax uses the standard Mermaid syntax for defining diagrams. For more information, see “Diagram Syntax” in the Mermaid documentation.

Edit this page