Diagrams with Mermaid

What are Mermaid diagrams

Mermaid is a syntax similar to Markdown where you can use text to describe and automatically generate diagrams. With Mermaid, you can generate Flow charts, UML diagrams, Pie charts, Gantt diagrams, Entity Relationship diagrams, and more.

An Entity Relationship diagram example

  
    %%{ init: {'theme': 'forest'} }%%
  
  erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINEITEM : contains
    PRODUCT ||--o{ LINEITEM : is_listed_in
    CUSTOMER {
        string Name
        string Email
        string Address
    }
    PRODUCT {
        string ProductName
        float Price
    }
    ORDER {
        date DateOrdered
        string Status
    }
    LINEITEM {
        int Quantity
    }

Using Mermaid in your blog post

The diagram shortcode allows you to easily embed Mermaid diagrams in your blog posts, with an option to configure its appearance.

Basic Usage

To use the shortcode in your blog post, you would use the following format:

{% diagram() %}
Your Mermaid diagram code here
{% end %}

Replace Your Mermaid diagram code here with your actual Mermaid diagram code.

To load the necessary JavaScript to render the Mermaid diagram, you need to enable it in the front matter of your blog post by setting the value for extra.diagram to true:

+++
[extra]
diagram = true
+++

Configuring the Appearance

The shortcode supports an optional init parameter, that allows you to specify configuration options for Mermaid, particularly changing the appearance of the diagrams through the theme.

For example, to apply the forest theme:

{% diagram(init="{'theme': 'forest'}") %}
Your Mermaid diagram code here
{% end %}

Providing init Configuration

When using the init parameter, the configuration should be a string wrapped in double quotes. Inside this string, use single quotes for keys and values.

Here's a more advanced example with multiple configuration options:

{% diagram(init="{'theme': 'forest', 'themeVariables': {'primaryColor': '#FF0000'}}") %}
Your Mermaid diagram code here
{% end %}

In this example, we're using the forest theme and changing the primary color to red (#FF0000).

Note: Ensure that you use single quotes inside the double quotes for the configuration to work correctly.

Putting it all together

Use the shortcode by enclosing your Mermaid diagram code with it. To change the look of the Mermaid theme, provide values for the init parameter. Always enclose the init value with double quotes, and use single quotes inside the configuration string. With this shortcode in place, integrating and customizing Mermaid diagrams in your blog posts becomes easy.

Explaining Mermaid diagram code

Here is how the diagram rendered above is embedded in this blog post as a code block. Because it is the same code as the diagram above, extra care has to be taken to prevent Mermaid from rendering it as a diagram. Use Zola’s ignored shortcode syntax in the code block, so the code stays visible but is not executed. For example, use {%/* for displaying {%, and */%} for displaying %}.

{% diagram(init="{'theme': 'forest'}") %}
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINEITEM : contains
    PRODUCT ||--o{ LINEITEM : is_listed_in
    CUSTOMER {
        string Name
        string Email
        string Address
    }
    PRODUCT {
        string ProductName
        float Price
    }
    ORDER {
        date DateOrdered
        string Status
    }
    LINEITEM {
        int Quantity
    }
{% end %}