<preclass="css"><code>bower install mermaid --save-dev</code></pre><preclass="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>
<p>Checkout the <ahref="https://github.com/knsv/mermaid/releases">latest version</a> and <ahref="https://github.com/knsv/mermaid/tree/master/dist">other styles</a> such as <code>forest</code> and <code>dark</code>.</p>
<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'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 <ahref="https://rawgit.com/">https://rawgit.com/</a></p>
<h2id="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>
<h3id="include-mermaid-on-your-web-page-">Include mermaid on your web page:</h3>
<script>mermaid.initialize({startOnLoad:true});</script></code></pre><p>Further down on your page mermaid will look for tags with <code>class="mermaid"</code>. From these tags mermaid will try to<br>read the chart definiton which will be replaced with the svg chart.</p>
<h3id="define-a-chart-like-this-">Define a chart like this:</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>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>
<p>By default, <strong>mermaid.init</strong> will be called when the document is ready, finding all elements with<br><code>class="mermaid"</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>
<preclass="css"><code>mermaid.init({noteMargin: 10}, ".someOtherClass");</code></pre><p>Or with no config object, and a jQuery selection:</p>
<preclass="css"><code>mermaid.init(undefined, $("#someId .yetAnotherClass"));</code></pre><asideclass="warning">This type of integration is deprecated instead the preferred way of handling more complex integration is to us the mermaidAPI instead.</aside>
<h2id="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 <ahref="http://browserify.org/">http://browserify.org/</a> website.</p>
<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>
<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>
<preclass="css"><code> var insertSvg = function(svgCode, bindFunctions){
<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>
<h2id="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>
<preclass="css"><code> var renderer = new marked.Renderer();
<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>
<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 <ahref="http://knsv.github.io/mermaid/index.html#configuration28">in the mermaidAPI documentation</a>.</p>
<h2id="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>
</script></code></pre><asideclass="success">This is the preferred way of configuring mermaid.</aside>
<h2id="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>
<preclass="css"><code>mermaid.startOnLoad = true;</code></pre><asideclass="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>
<h2id="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>
<preclass="css"><code>mermaid_config.startOnLoad = true;</code></pre><asideclass="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>
<h2id="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>
<preclass="css"><code>mermaid_config.startOnLoad = true;</code></pre><asideclass="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>
