Mermaid Js Syntax

30-04-2021

Mermaid Js Syntax

Mermaid Editor is vscode extension inspired by official mermaid live editor to provide the following features:

Live edit .mmd file with mermaid.js diagram
Syntax highliting.
Generate image file from .mmd file with preferred format (png, jpg, webp and svg).
Customize configuration for individual mmd diagram by using atrribute which is available in this extension.

Usage

The extension is activated when opening .mmd file.

Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams and gantt charts. Content delivery at its finest. Cdnjs is a free and open-source CDN. Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams, gantt charts and git graphs. Mermaid lets you generate diagrams and flowcharts with Markdown-like syntax. It’s easy to use, free, and open source. Mermaid lets you simplify documentation and avoid bulky tools when explaining. Generation of diagrams and flowcharts from text in a similar manner as markdown by using mermaid.js.

Open live preview

Select Mermaid:Preview mermaid from context menu or command palette
Click Mermaid:Preview diagram icon at right corner
ctrl+alt+[ on .mmd file

Generate image

Generate command is only available when .mmd file is opened and live preview is activated.

Select Mermaid:Generate image from context menu or command palette
Click Mermaid:Generate image icon
ctrl+alt+] on .mmd file

Change scale of live preview

Zoom in/out is supported for live preview.

Select Mermaid:Zoom in, Mermaid:Zoom out, Mermaid:Reset zoom, Mermaid:Zoom to specific scale from command palette
Click Mermaid:Zoom in, Mermaid:Zoom out icon focusing live preview panel
Zoom out: ctrl+alt+-
Zoom in: ctrl+alt+=
Reset zoom: ctrl+alt+0

Attributes

This extension supports attribute to specify preferred configuration for each .mmd file. The attribute have to be described in comment of mermaid syntax.

@config{path_to_config}

Each .mmd file can be associated with mermaid configuration. With this attribute, .mmd file can read specified configuration. path_to_config have to be described as relative path to the config json file from associated .mmd file. If this attribute is not provided, default config file setting up in mermaid-editor.preview.defaultMermaidConfig is applied.

@backgroundColor{color}

Each .mmd file can be associated with preferred background color. With this attribute, .mmd can read specifed background color with CSS style property format.If this attribute is not provided, default background color setting up in mermaid-editor.preview.backgroundColor is applied. The followings are example.

Configuration

Settings for look & feel in preview or image generator.

Setting	Default	Description
mermaid-editor.preview.defaultMermaidConfig	relative path to the default configuration json file for mermaidjs.
mermaid-editor.preview.backgroundColor	white	default background color for live preview and generated image
mermaid-editor.preview.errorOutputOnSave	true	show error output console whe saving file if there's error message. Note: Error output in the console itself is always available regardless of this configuration.
mermaid-editor.generate.type	svg	output image file type [svg, png, jpg, webp]
mermaid-editor.generate.outputPath	relative path to the output target directory from project root
mermaid-editor.generate.useCurrentPath	true	use relative output path as same as target mmd file instead of 'outputPath'
mermaid-editor.generate.width	800	width of the output image
mermaid-editor.generate.height	600	height of the output image

Credits

This extension uses Feather icon set under CC BY 3.0

Installation

Either use the npm or bower package managers as per below:

Or download a javascript bundle and a stylesheet, e.g. the urls below are for the default style and the all-in-one javascript - note that #version# should be replaced with version of choice:

Ex:

Checkout the latest version and other styles such as forest and dark.

There are some bundles to choose from:

mermaid.js, mermaid.min.js This bundle contains all the javascript libraries you need to run mermaid
mermaid.slim.js, mermaid.slim.min.js This bundle does not contain d3 which is useful for sites that already have d3 in place
mermaidAPI.js, mermaidAPI.min.js, This bundle does not contain the web integration provided in the other packages but has a render function instead returns svg code.

Important:

It's best to use a specific tag or commit hash in the URL (not a branch). Files are cached permanently after the first request.

Read more about that at https://rawgit.com/

Simple usage on a web page

The easiest way to integrate mermaid on a web page requires two elements:

Inclusion of the mermaid framework in the html page using a script tag
A graph definition on the web page

If these things are in place mermaid listens to the page load event and when fires, when the page has loaded, it will
locate the graphs n the page and transform them to svg files.

Include mermaid on your web page:

Further down on your page mermaid will look for tags with class='mermaid'. From these tags mermaid will try to
read the chart definiton which will be replaced with the svg chart.

Define a chart like this:

Would end up like this:

An id is also added to mermaid tags without id.

Labels out of bounds

If you use dynamically loaded fonts that are loaded through CSS, such as Google fonts, mermaid should wait for the
whole page to have been loaded (dom + assets, particularly the fonts file).

$(document).load(function() {
mermaid.initialize();
});
over

$(document).ready(function() {
mermaid.initialize();
});

Not doing so will most likely result in mermaid rendering graphs that have labels out of bounds. The default integration
in mermaid uses the window.load event to start rendering.

Calling mermaid.init

By default, mermaid.init will be called when the document is ready, finding all elements with
class='mermaid'. If you are adding content after mermaid is loaded, or otherwise need
finer-grained control of this behavior, you can call init yourself with:

a configuration object
some nodes, as
- a node
- an a array-like of nodes
- or W3C selector that will find your nodes

Example:

Or with no config object, and a jQuery selection:

This type of integration is deprecated instead the preferred way of handling more complex integration is to us the mermaidAPI instead.

Usage with browserify

The reader is assumed to know about CommonJS style of module handling and how to use browserify. If not a good place
to start would be http://browserify.org/ website.

Minimalistic javascript:

Bundle the javascript with browserify.

Us the created bundle on a web page as per example below:

API usage

The main idea with the API is to be able to call a render function with graph defintion as a string. The render function
will render the graph and call a callback with the resulting svg code. With this approach it is up to the site creator to
fetch the graph definition from the site, perhaps from a textarea, render it and place the graph somewhere in the site.

To do this, include mermaidAPI on your web website instead of mermaid.js. The example below show an outline of how this
could be used. The example just logs the resulting svg to the javascript console.

Sample of API usage together with browserify

Binding events

Sometimes the generated graph also has defined interactions like tooltip and click events. When using the API one must
add those events after the graph has been inserted into the DOM.

The example code below is an extract of wheat mermaid does when using the API. The example show how it is possible to
bind events to a svg when using the API for rendering.

The graph is generated using the render call.
After generation the render function calls the provided callback function, in this case its called insertSvg.
The callback function is called with two parameters, the svg code of the generated graph and a function. This
function binds events to the svg after it is inserted into the DOM.
Insert the svg code into the DOM for presentation
Call the binding function that bainds the events

Example of a marked renderer

This is the renderer used for transforming the documentation from markdown to html with mermaid diagrams in the html.

Another example in coffeescript that also includes the mermaid script tag into the generated markup.

Advanced usage

Error handling

When the parser encounters invalid syntax the mermaid.parseError function is called. It is possible to override this
function in order to handle the error in an application specific way.

Parsing text without rendering

It is also possible to validate the syntax before rendering in order to streamline the user experience. The function
mermaid.parse(txt) takes a text string as an argument and returns true if the text is syntactically correct and
false if it is not. The parseError function will be called when the parse function returns false.

The code-example below in meta code illustrates how this could work:

Mermaid takes a number of options which lets you tweak the rendering of the diagrams. Currently there are three ways of
setting the options in mermaid.

Instantiation of the configuration using the initialize call
Using the global mermaid object - deprecated
using the global mermaid_config object - deprecated
Instantiation of the configuration using the mermaid.init call

The list above has two ways to many of doing this. Three are deprecated and will eventually be removed. The list of
configuration objects are described in the mermaidAPI documentation.

Using the mermaidAPI.initialize/mermaid.initialize call

The future proof way of setting the configuration is by using the initialization call to mermaid or mermaidAPi depending
on what kind of integration you use.

This is the preferred way of configuring mermaid.

Using the mermaid object

Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this
approach are:

mermaid.startOnLoad
mermaid.htmlLabels

This way of setting the configuration is deprecated instead the preferred way of is to use the initialize method. This functionality is only kept for not breaking existing integrations

Using the mermaid_config

Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this
approach are:

mermaid_config.startOnLoad
mermaid_config.htmlLabels

This way of setting the configuration is deprecated instead the preferred way of is to use the initialize method. This functionality is only kept for not breaking existing integrations

Using the mermaid.init call