mermaid/build/www/usage.html

Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams and gantt charts.

<h1 id="usage">Usage</h1>
<h2 id="installation">Installation</h2>
<p>Either use the npm or bower package managers as per below:</p>
<pre class="css"><code>bower install mermaid --save-dev</code></pre><pre class="css"><code>npm install mermaid --save-dev</code></pre><p>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:</p>
<pre class="css"><code>https://cdn.rawgit.com/knsv/mermaid/#version#/dist/mermaid.css
https://cdn.rawgit.com/knsv/mermaid/#version#/dist/mermaid.min.js</code></pre><p>Ex:</p>
<ul>
<li><a href="https://cdn.rawgit.com/knsv/mermaid/6.0.0/dist/mermaid.min.js">js version 6.0.0</a></li>
</ul>
<p>Checkout the <a href="https://github.com/knsv/mermaid/releases">latest version</a> and <a href="https://github.com/knsv/mermaid/tree/master/dist">other styles</a> such as <code>forest</code> and <code>dark</code>.</p>
<p>There are some bundles to choose from:</p>
<ul>
<li>mermaid.js, mermaid.min.js This bundle contains all the javascript libraries you need to run mermaid</li>
<li>mermaid.slim.js, mermaid.slim.min.js This bundle does not contain d3 which is useful for sites that already have d3 in place</li>
<li>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.</li>
</ul>
<p><strong> Important: </strong></p>
<blockquote>
<p>It&#39;s best to use a specific tag or commit hash in the URL (not a branch). Files are cached permanently after the first request.</p>
</blockquote>
<p>Read more about that at <a href="https://rawgit.com/">https://rawgit.com/</a></p>
<h2 id="simple-usage-on-a-web-page">Simple usage on a web page</h2>
<p>The easiest way to integrate mermaid on a web page requires two elements:</p>
<ol>
<li>Inclusion of the mermaid framework in the html page using a script tag</li>
<li>A graph definition on the web page</li>
</ol>
<p>If these things are in place mermaid listens to the page load event and when fires, when the page has loaded, it will<br>locate the graphs n the page and transform them to svg files.</p>
<h3 id="include-mermaid-on-your-web-page-">Include mermaid on your web page:</h3>
<pre class="css"><code><link rel="stylesheet" href="mermaid.css">
&lt;script src=&quot;mermaid.min.js&quot;&gt;&lt;/script&gt;
&lt;script&gt;mermaid.initialize({startOnLoad:true});&lt;/script&gt;</code></pre><p>Further down on your page mermaid will look for tags with <code>class=&quot;mermaid&quot;</code>. From these tags mermaid will try to<br>read the chart definiton which will be replaced with the svg chart.</p>
<h3 id="define-a-chart-like-this-">Define a chart like this:</h3>
<pre class="css"><code>&lt;div class=&quot;mermaid&quot;&gt;
    CHART DEFINITION GOES HERE
&lt;/div&gt;</code></pre><p>Would end up like this:</p>
<pre class="css"><code>&lt;div class=&quot;mermaid&quot; id=&quot;mermaidChart0&quot;&gt;
    &lt;svg&gt;
        Chart ends up here
    &lt;/svg&gt;
&lt;/div&gt;</code></pre><p>An id is also added to mermaid tags without id.</p>
<h3 id="labels-out-of-bounds">Labels out of bounds</h3>
<p>If you use dynamically loaded fonts that are loaded through CSS, such as Google fonts, mermaid should wait for the<br>whole page to have been loaded (dom + assets, particularly the fonts file).</p>
<p>$(document).load(function() {<br>    mermaid.initialize();<br>});<br>over</p>
<p>$(document).ready(function() {<br>    mermaid.initialize();<br>});</p>
<p>Not doing so will most likely result in mermaid rendering graphs that have labels out of bounds. The default integration<br>in mermaid uses the window.load event to start rendering.</p>
<h3 id="calling-mermaid-init-">Calling <strong>mermaid.init</strong></h3>
<p>By default, <strong>mermaid.init</strong> will be called when the document is ready, finding all elements with<br><code>class=&quot;mermaid&quot;</code>. If you are adding content after mermaid is loaded, or otherwise need<br>finer-grained control of this behavior, you can call <code>init</code> yourself with:</p>
<ul>
<li>a configuration object</li>
<li>some nodes, as<ul>
<li>a node</li>
<li>an a array-like of nodes</li>
<li>or W3C selector that will find your nodes</li>
</ul>
</li>
</ul>
<p>Example:</p>
<pre class="css"><code>mermaid.init({noteMargin: 10}, ".someOtherClass");</code></pre><p>Or with no config object, and a jQuery selection:</p>
<pre class="css"><code>mermaid.init(undefined, $("#someId .yetAnotherClass"));</code></pre><aside class="warning">This type of integration is deprecated instead the preferred way of handling more complex integration is to us the mermaidAPI instead.</aside>

<h2 id="usage-with-browserify">Usage with browserify</h2>
<p>The reader is assumed to know about CommonJS style of module handling and how to use browserify. If not a good place<br>to start would be <a href="http://browserify.org/">http://browserify.org/</a> website.</p>
<p>Minimalistic javascript:</p>
<pre class="css"><code>mermaid = require('mermaid');
console.log('Test page! mermaid version'+mermaid.version());</code></pre><p>Bundle the javascript with browserify.</p>
<p>Us the created bundle on a web page as per example below:</p>
<pre class="css"><code>&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
    &lt;meta charset=&quot;UTF-8&quot;&gt;
    &lt;link rel=&quot;stylesheet&quot; href=&quot;mermaid.css&quot; /&gt;
    &lt;script src=&quot;bundle.js&quot;&gt;&lt;/script&gt;
&lt;/head&gt;
&lt;body&gt;
    &lt;div class=&quot;mermaid&quot;&gt;
        graph LR
            A--&gt;B
            B--&gt;C
            C--&gt;A
            D--&gt;C
    &lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;</code></pre><h2 id="api-usage">API usage</h2>
<p>The main idea with the API is to be able to call a render function with graph defintion as a string. The render function<br>will render the graph and call a callback with the resulting svg code. With this approach it is up to the site creator to<br>fetch the graph definition from the site, perhaps from a textarea, render it and place the graph somewhere in the site.</p>
<p>To do this, include mermaidAPI on your web website instead of mermaid.js. The example below show an outline of how this<br>could be used. The example just logs the resulting svg to the javascript console.</p>
<pre class="css"><code>&lt;script src=&quot;mermaidAPI.js&quot;&gt;&lt;/script&gt;

&lt;script&gt;
    mermaidAPI.initialize({
        startOnLoad:false
    });
    $(function(){
    // Example of using the API
        var element = document.querySelector("#graphDiv");

        var insertSvg = function(svgCode, bindFunctions){
            element.innerHTML = svgCode;
        };

        var graphDefinition = 'graph TB\na-->b';
        var graph = mermaidAPI.render('graphDiv', graphDefinition, insertSvg);
    });
&lt;/script&gt;</code></pre><h2 id="sample-of-api-usage-together-with-browserify">Sample of API usage together with browserify</h2>
<pre class="css"><code>$ = 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);
});</code></pre><h3 id="binding-events">Binding events</h3>
<p>Sometimes the generated graph also has defined interactions like tooltip and click events. When using the API one must<br>add those events after the graph has been inserted into the DOM.</p>
<p>The example code below is an extract of wheat mermaid does when using the API. The example show how it is possible to<br>bind events to a svg when using the API for rendering.</p>
<pre class="css"><code>     var insertSvg = function(svgCode, bindFunctions){
         element.innerHTML = svgCode;
         if(typeof callback !== 'undefined'){
             callback(id);
         }
         bindFunctions(element);
     };

     var id = 'theGraph';


     mermaidAPI.render(id,txt,insertSvg, element);</code></pre><ol>
<li>The graph is generated using the render call. </li>
<li>After generation the render function calls the provided callback function, in this case its called insertSvg.</li>
<li>The callback function is called with two parameters, the svg code of the generated graph and a function. This<br>function binds events to the svg <strong>after</strong> it is inserted into the DOM.</li>
<li>Insert the svg code into the DOM for presentation</li>
<li>Call the binding function that bainds the events</li>
</ol>
<h2 id="example-of-a-marked-renderer">Example of a marked renderer</h2>
<p>This is the renderer used for transforming the documentation from markdown to html with mermaid diagrams in the html.</p>
<pre class="css"><code>    var renderer = new marked.Renderer();
    renderer.code = function (code, language) {
        if(code.match(/^sequenceDiagram/)||code.match(/^graph/)){
            return '&lt;div class="mermaid">'+code+'&lt;/div>';
        }
        else{
            return '&lt;pre>&lt;code>'+code+'&lt;/code>&lt;/pre>';
        }
    };</code></pre><p>Another example in coffeescript that also includes the mermaid script tag into the generated markup.</p>
<pre class="css"><code>marked = require &#39;marked&#39;

module.exports = (options) -&gt;
  hasMermaid = false
  renderer = new marked.Renderer()
  renderer.defaultCode = renderer.code
  renderer.code = (code, language) -&gt;
    if language is &#39;mermaid&#39;
      html = &#39;&#39;
      if not hasMermaid
        hasMermaid = true
        html += &#39;&amp;ltscript src=&quot;&#39;+options.mermaidPath+&#39;&quot;&gt;&lt;/script&gt;&#39;
      html + &#39;&amp;ltdiv class=&quot;mermaid&quot;&gt;&#39;+code+&#39;&lt;/div&gt;&#39;
    else
      @defaultCode(code, language)

  renderer</code></pre><h2 id="advanced-usage">Advanced usage</h2>
<p><strong>Error handling</strong></p>
<p>When the parser encounters invalid syntax the <strong>mermaid.parseError</strong> function is called. It is possible to override this<br>function in order to handle the error in an application specific way.</p>
<p><strong>Parsing text without rendering</strong></p>
<p>It is also possible to validate the syntax before rendering in order to streamline the user experience. The function<br><strong>mermaid.parse(txt)</strong> takes a text string as an argument and returns true if the text is syntactically correct and<br>false if it is not. The parseError function will be called when the parse function returns false.</p>
<p>The code-example below in meta code illustrates how this could work:</p>
<pre class="css"><code>
mermaid.parseError = function(err,hash){
    displayErrorInGui(err);
};

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

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

bindEventHandler('change', 'code', textFieldUpdated);</code></pre><h1 id="configuration">Configuration</h1>
<p>Mermaid takes a number of options which lets you tweak the rendering of the diagrams. Currently there are three ways of<br>setting the options in mermaid.</p>
<ol>
<li>Instantiation of the configuration using the initialize call</li>
<li><em>Using the global mermaid object</em> - deprecated</li>
<li><em>using the global mermaid_config object</em> - deprecated</li>
<li>Instantiation of the configuration using the <strong>mermaid.init</strong> call</li>
</ol>
<p>The list above has two ways to many of doing this. Three are deprecated and will eventually be removed. The list of<br>configuration objects are described <a href="http://knsv.github.io/mermaid/index.html#configuration28">in the mermaidAPI documentation</a>.</p>
<h2 id="using-the-mermaidapi-initialize-mermaid-initialize-call">Using the mermaidAPI.initialize/mermaid.initialize call</h2>
<p>The future proof way of setting the configuration is by using the initialization call to mermaid or mermaidAPi depending<br>on what kind of integration you use.</p>
<pre class="css"><code>    &lt;script src=&quot;../dist/mermaid.js&quot;&gt;&lt;/script&gt;
    &lt;script&gt;
        var config = {
            startOnLoad:true,
            flowchart:{
                    useMaxWidth:false,
                    htmlLabels:true
            }
        };
        mermaid.initialize(config);
    &lt;/script&gt;</code></pre><aside class="success">This is the preferred way of configuring mermaid.</aside>


<h2 id="using-the-mermaid-object">Using the mermaid object</h2>
<p>Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this<br>approach are:</p>
<ul>
<li>mermaid.startOnLoad</li>
<li>mermaid.htmlLabels</li>
</ul>
<pre class="css"><code>mermaid.startOnLoad = true;</code></pre><aside class="info">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</aside>

<h2 id="using-the-mermaid_config">Using the mermaid_config</h2>
<p>Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this<br>approach are:</p>
<ul>
<li>mermaid_config.startOnLoad</li>
<li>mermaid_config.htmlLabels</li>
</ul>
<pre class="css"><code>mermaid_config.startOnLoad = true;</code></pre><aside class="info">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</aside>

<h2 id="using-the-mermaid-init-call">Using the mermaid.init call</h2>
<p>Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this<br>approach are:</p>
<ul>
<li>mermaid_config.startOnLoad</li>
<li>mermaid_config.htmlLabels</li>
</ul>
<pre class="css"><code>mermaid_config.startOnLoad = true;</code></pre><aside class="info">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</aside>