mermaid
Version:
Markdownish syntax for generating flowcharts, sequence diagrams and gantt charts.
294 lines (274 loc) • 15.2 kB
HTML
<html>
<head>
<meta charset="utf-8">
<meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
<title>mermaid - Generation of diagrams and flowcharts from text in a similar manner as markdown.</title>
<link href="stylesheets/screen.css" rel="stylesheet" type="text/css" media="screen"/>
<link href="stylesheets/print.css" rel="stylesheet" type="text/css" media="print"/>
<link href="stylesheets/mermaid.forest.css" rel="stylesheet" type="text/css"/>
<link href="stylesheets/solarized_light.css" rel="stylesheet" type="text/css"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
<script src="javascripts/lib/mermaid.js"></script>
<script src="javascripts/all.js" type="text/javascript"></script>
<script src="javascripts/highlight.pack.js" type="text/javascript"></script>
<script>
var g = function (hljs) {
var r = "[a-z'][a-zA-Z0-9_']*", c = "(" + r + ":" + r + "|" + r + ")";
var keyw = {
keyword: 'graph sequenceDiagram participant loop end',
typename: 'Note',
literal: "false true left right"
};
return {
case_insensitive: false,
aliases: ["mermaid"],
k: keyw,
i: 'for',
c: [{
cN: "function",
b: "^" + r + "\\s*\\(",
e: "->",
rB: !0,
i: "\\(|#|//|/\\*|\\\\|:|;",
starts: {
e: ";|\\.", k: keyw, c: [
{cN: "comment", b: "%", e: "$"}
]
}
},
{cN: "comment", b: "%", e: "$"}
]
};
};
hljs.registerLanguage('mermaid', g);
hljs.initHighlightingOnLoad();
$(function () {
setupLanguages(["shell", "javascript", "html", "css","mermaid"]);
});
</script>
</head>
<body class="index">
<a href="#" id="nav-button">
<span>
NAV
<img src="images/navbar.png"/>
</span>
</a>
<div class="tocify-wrapper">
<img src="images/logo.png"/>
<div class="lang-selector" style="display:none">
<a href="#" data-language-name="shell">shell</a>
<a href="#" data-language-name="javascript">javascript</a>
<a href="#" data-language-name="html">html</a>
<a href="#" data-language-name="css">css</a>
</div>
<div class="search">
<input type="text" class="search" id="input-search" placeholder="Search">
</div>
<ul class="search-results"></ul>
<div id="toc">
</div>
<ul class="toc-footer">
<li><a href='http://github.com/tripit/slate'>Documentation Powered by Slate</a></li>
</ul>
</div>
<div class="page-wrapper">
<div class="dark-box"></div>
<div class="content">
<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 javascript files as per the url below, note that #version# should be replaced with version of choice:</p>
<pre class="css"><code>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/0.5.1/dist/mermaid.min.js">version 0.5.1</a></li>
</ul>
<p>There are some bundles to choose from:</p>
<ul>
<li>mermaid.js, mermaid.min.js This bundle contains everything 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'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><script src="mermaid.min.js"></script>
<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>
<h3 id="define-a-chart-like-this-">Define a chart like this:</h3>
<pre class="css"><code><div class="mermaid">
CHART DEFINITION GOES HERE
</div></code></pre><p>Would end up like this:</p>
<pre class="css"><code><div class="mermaid" id="mermaidChart0">
<svg>
Chart ends up here
</svg>
</div></code></pre><p>An id is also added to mermaid tags without id.</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="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>
<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><!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<link rel="stylesheet" href="mermaid.css" />
<script src="bundle.js"></script>
</head>
<body>
<div class="mermaid">
graph LR
A-->B
B-->C
C-->A
D-->C
</div>
</body>
</html></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><script src="mermaidAPI.js"></script>
<script>
mermaidAPI.initialize({
startOnLoad:false
});
// Example of using the API
$(function(){
var graphDefinition = 'graph TB\na-->b';
var graph = mermaidAPI.render(graphDefinition);
$("#graphDiv").html(graph);
});
</script></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><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 '<div class="mermaid">'+code+'</div>';
}
else{
return '<pre><code>'+code+'</code></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 '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 += '&ltscript src="'+options.mermaidPath+'"></script>'
html + '&ltdiv class="mermaid">'+code+'</div>'
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> <script src="../dist/mermaid.js"></script>
<script>
var config = {
startOnLoad:true,
flowchart:{
useMaxWidth:false,
htmlLabels:true
}
};
mermaid.initialize(config);
</script></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>
</div>
<div class="dark-box">
<div class="lang-selector">
<a href="#" data-language-name="shell">shell</a>
<a href="#" data-language-name="ruby">ruby</a>
<a href="#" data-language-name="python">python</a>
</div>
</div>
</div>
</body>
</html>