mirror of
https://github.com/mermaid-js/mermaid.git
synced 2025-11-26 23:54:09 +01:00
Adding docs into core repo again
This commit is contained in:
Knut Sveidqvist
342
docs/usage.md
Normal file
342
docs/usage.md
Normal file
@@ -0,0 +1,342 @@
|
||||
# Usage
|
||||
|
||||
## Installation
|
||||
|
||||
### npm package
|
||||
|
||||
```
|
||||
yarn add mermaid
|
||||
```
|
||||
|
||||
### CDN
|
||||
|
||||
https://unpkg.com/mermaid/
|
||||
|
||||
Please note that you can switch versions through the dropdown box on top right.
|
||||
|
||||
|
||||
## Simple usage on a web page
|
||||
|
||||
The easiest way to integrate mermaid on a web page requires two elements:
|
||||
1. Inclusion of the mermaid framework in the html page using a script tag
|
||||
2. A graph definition on the web page
|
||||
|
||||
If these things are in place mermaid listens to the page load event and when fires, when the page has loaded, it will
|
||||
locate the graphs n the page and transform them to svg files.
|
||||
|
||||
### Include mermaid on your web page:
|
||||
|
||||
```html
|
||||
<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.
|
||||
|
||||
|
||||
### Define a chart like this:
|
||||
|
||||
```html
|
||||
<div class="mermaid">
|
||||
CHART DEFINITION GOES HERE
|
||||
</div>
|
||||
```
|
||||
|
||||
Would end up like this:
|
||||
|
||||
```html
|
||||
<div class="mermaid" id="mermaidChart0">
|
||||
<svg>
|
||||
Chart ends up here
|
||||
</svg>
|
||||
</div>
|
||||
```
|
||||
|
||||
An id is also added to mermaid tags without id.
|
||||
|
||||
### Simple full example:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<link rel="stylesheet" href="mermaid.min.css">
|
||||
</head>
|
||||
<body>
|
||||
<div class="mermaid">
|
||||
graph LR
|
||||
A --- B
|
||||
B-->C[fa:fa-ban forbidden]
|
||||
B-->D(fa:fa-spinner);
|
||||
</div>
|
||||
<script src="mermaid.min.js"></script>
|
||||
<script>mermaid.initialize({startOnLoad:true});</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
### Labels out of bounds
|
||||
|
||||
If you use dynamically loaded fonts that are loaded through CSS, such as Google fonts, mermaid should wait for the
|
||||
whole page to have been loaded (dom + assets, particularly the fonts file).
|
||||
|
||||
```javascript
|
||||
$(document).load(function() {
|
||||
mermaid.initialize();
|
||||
});
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```javascript
|
||||
$(document).ready(function() {
|
||||
mermaid.initialize();
|
||||
});
|
||||
```
|
||||
|
||||
Not doing so will most likely result in mermaid rendering graphs that have labels out of bounds. The default integration
|
||||
in mermaid uses the window.load event to start rendering.
|
||||
|
||||
### 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:
|
||||
|
||||
```javascript
|
||||
mermaid.init({noteMargin: 10}, ".someOtherClass");
|
||||
```
|
||||
|
||||
Or with no config object, and a jQuery selection:
|
||||
|
||||
```javascript
|
||||
mermaid.init(undefined, $("#someId .yetAnotherClass"));
|
||||
```
|
||||
|
||||
> **Warning** This type of integration is deprecated instead the preferred way of handling more complex integration is to us the mermaidAPI instead.
|
||||
|
||||
|
||||
## Usage with webpack
|
||||
|
||||
mermaid fully supports webpack. Here is a [working demo](https://github.com/mermaidjs/mermaid-webpack-demo).
|
||||
|
||||
|
||||
## API usage
|
||||
|
||||
The main idea with the API is to be able to call a render function with graph defintion as a string. The render function
|
||||
will render the graph and call a callback with the resulting svg code. With this approach it is up to the site creator to
|
||||
fetch the graph definition from the site, perhaps from a textarea, render it and place the graph somewhere in the site.
|
||||
|
||||
To do this, include mermaidAPI on your web website instead of mermaid.js. The example below show an outline of how this
|
||||
could be used. The example just logs the resulting svg to the javascript console.
|
||||
|
||||
```html
|
||||
<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>
|
||||
```
|
||||
|
||||
|
||||
### Binding events
|
||||
|
||||
Sometimes the generated graph also has defined interactions like tooltip and click events. When using the API one must
|
||||
add those events after the graph has been inserted into the DOM.
|
||||
|
||||
The example code below is an extract of what mermaid does when using the API. The example shows how it is possible to
|
||||
bind events to an svg when using the API for rendering.
|
||||
|
||||
```javascript
|
||||
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);
|
||||
```
|
||||
|
||||
1. The graph is generated using the render call.
|
||||
2. After generation the render function calls the provided callback function, in this case it's called insertSvg.
|
||||
3. The callback function is called with two parameters, the svg code of the generated graph and a function. This function binds events to the svg **after** it is inserted into the DOM.
|
||||
4. Insert the svg code into the DOM for presentation
|
||||
5. Call the binding function that binds the events
|
||||
|
||||
|
||||
## Example of a marked renderer
|
||||
|
||||
This is the renderer used for transforming the documentation from markdown to html with mermaid diagrams in the html.
|
||||
|
||||
```javascript
|
||||
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.
|
||||
|
||||
```CoffeeScript
|
||||
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:
|
||||
|
||||
```javascript
|
||||
mermaid.parseError = function(err,hash){
|
||||
displayErrorInGui(err);
|
||||
};
|
||||
|
||||
var textFieldUpdated = function(){
|
||||
var textStr = getTextFromFormField('code');
|
||||
|
||||
if(mermaid.parse(textStr)){
|
||||
reRender(textStr)
|
||||
}
|
||||
};
|
||||
|
||||
bindEventHandler('change', 'code', textFieldUpdated);
|
||||
```
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
Mermaid takes a number of options which lets you tweak the rendering of the diagrams. Currently there are three ways of
|
||||
setting the options in mermaid.
|
||||
|
||||
1. Instantiation of the configuration using the initialize call
|
||||
2. *Using the global mermaid object* - deprecated
|
||||
3. *using the global mermaid_config object* - deprecated
|
||||
4. Instantiation of the configuration using the **mermaid.init** call
|
||||
|
||||
The list above has two ways to many of doing this. Three are deprecated and will eventually be removed. The list of
|
||||
configuration objects are described [in the mermaidAPI documentation](mermaidAPI.html).
|
||||
|
||||
|
||||
## Using the `mermaidAPI.initialize`/`mermaid.initialize` call
|
||||
|
||||
The future proof way of setting the configuration is by using the initialization call to mermaid or mermaidAPi depending
|
||||
on what kind of integration you use.
|
||||
|
||||
```html
|
||||
<script src="../dist/mermaid.js"></script>
|
||||
<script>
|
||||
var config = {
|
||||
startOnLoad:true,
|
||||
flowchart:{
|
||||
useMaxWidth:false,
|
||||
htmlLabels:true
|
||||
}
|
||||
};
|
||||
mermaid.initialize(config);
|
||||
</script>
|
||||
```
|
||||
|
||||
> **Success** This is the preferred way of configuring mermaid.
|
||||
|
||||
|
||||
## Using the mermaid object
|
||||
|
||||
Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this
|
||||
approach are:
|
||||
|
||||
* mermaid.startOnLoad
|
||||
* mermaid.htmlLabels
|
||||
|
||||
```
|
||||
mermaid.startOnLoad = true;
|
||||
```
|
||||
|
||||
> **Warning** 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
|
||||
|
||||
## Using the mermaid_config
|
||||
|
||||
Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this
|
||||
approach are:
|
||||
|
||||
* mermaid_config.startOnLoad
|
||||
* mermaid_config.htmlLabels
|
||||
|
||||
```javascript
|
||||
mermaid_config.startOnLoad = true;
|
||||
```
|
||||
|
||||
> **Warning** 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
|
||||
|
||||
## Using the mermaid.init call
|
||||
|
||||
Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this
|
||||
approach are:
|
||||
|
||||
* mermaid_config.startOnLoad
|
||||
* mermaid_config.htmlLabels
|
||||
|
||||
```
|
||||
mermaid_config.startOnLoad = true;
|
||||
```
|
||||
|
||||
> **Warning** 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
|
||||
Reference in New Issue
Block a user