mirror of
https://github.com/mermaid-js/mermaid.git
synced 2025-01-14 06:43:25 +08:00
335 lines
17 KiB
HTML
335 lines
17 KiB
HTML
<!doctype 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 rel="stylesheet" href="fontawesome/css/font-awesome.min.css">
|
|
|
|
<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"]);
|
|
});
|
|
var callback = function(){
|
|
alert('A callback was triggered');
|
|
}
|
|
</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">
|
|
<div style="margin-left:5px;">
|
|
<a href="https://github.com/knsv/mermaid" class="github-button" >Star</a>
|
|
<a href="https://github.com/knsv/mermaid" class="github-button">Fork</a>
|
|
<a href="https://github.com/knsv/mermaid/archive/master.zip" class="github-button">Download</a>
|
|
</div>
|
|
<script async defer id="github-bjs" src="https://buttons.github.io/buttons.js"></script>
|
|
<li><a href='http://github.com/tripit/slate' style="color:grey">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>
|
|
<p>###Labels out of bounds</p>
|
|
<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="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
|
|
});
|
|
$(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);
|
|
});
|
|
</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><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 '<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>
|