mermaid/docs/usage.md

title	order
Usage	1

#Installation

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

bower install mermaid --save-dev

npm install mermaid --save-dev

Or download javascript files:

• mermaid including dependencies

There are some bundles to choose from:

• mermaid.js, mermaid.min.js This bundle contains everything you need to run mermaid
• mermaid.slim.js, mermaid.slim.min.js This bundle does not contain d3 which is usefull 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/

Usage

Include mermaid on your web page:

<script src="mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>

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.

A chart defined like this:

<div class="mermaid">
    CHART DEFINITION GOES HERE
</div>

Would end up like this:

<div class="mermaid" id="mermaidChart0">
    <svg>
        Chart ends up here
    </svg>
</div>

An id is also added to mermaid tags without id.

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:

mermaid.init({noteMargin: 10}, ".someOtherClass");

Or with no config object, and a jQuery selection:

mermaid.init(undefined, $("#someId .yetAnotherClass"));

#Usage with browserify Minimalistic javascript:

mermaid = require('mermaid');

#API usage Include mermaid on your web page:

<script src="mermaidAPI.js"></script>

<script>
    mermaidAPI.initialize({
        startOnLoad:false
        });
    $(function(){
        var graphDefinition = 'graph TB\na-->b';
        var graph = mermaidAPI.render(graphDefinition);
        $("#graphDiv").html(graph);
    });
</script>

#Sample API usage with browserify

$ = require('jquery');
mermaidAPI = require('mermaid').mermaidAPI;
mermaidAPI.initialize({
    startOnLoad:false
    });

$(function(){
    var graphDefinition = 'graph TB\na-->b';
    var cb = function(html){
	    console.log(html);
    }
    mermaidAPI.render('id1',graphDefinition,cb);
});

Example of marked renderer

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

    var renderer = new marked.Renderer();
    renderer.code = function (code, language) {
        if(code.match(/^sequenceDiagram/)||code.match(/^graph/)){
            return '<div class="mermaid">'+code+'</div>';
        }
        else{
            return '<pre><code>'+code+'</code></pre>';
        }
    };

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

marked = require 'marked'

module.exports = (options) ->
  hasMermaid = false
  renderer = new marked.Renderer()
  renderer.defaultCode = renderer.code
  renderer.code = (code, language) ->
    if language is 'mermaid'
      html = ''
      if not hasMermaid
        hasMermaid = true
        html += '<script src="'+options.mermaidPath+'"></script>'
      html + '<div class="mermaid">'+code+'</div>'
    else
      @defaultCode(code, language)

  renderer

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.parseError = function(err,hash){
    displayErrorInGui(err);
};

var textFieldUpdated = function(){
    var textStr = getTextFromFormField('code');

    if(mermaid.parse(textStr)){
        reRender(textStr)
    }
};

bindEventHandler('change', 'code', textFieldUpdated);