mermaid/Setup.md at 3c23de973563320c6e529952c66e0dc78b254ecd

mirror of https://github.com/mermaid-js/mermaid.git synced 2025-01-14 06:43:25 +08:00

Knut Sveidqvist da8e75f98a Merge from master with doc updates

2020-07-16 12:27:03 +02:00

33 KiB

Raw Blame History

mermaidAPI

This is the api to be used when optionally handling the integration with the web page, instead of using the default integration provided by mermaid.js.

The core of this api is the render function which, given a graph definition as text, renders the graph/diagram and returns an svg element for the graph.

It is is then up to the user of the API to make use of the svg, either insert it somewhere in the page or do something completely different.

In addition to the render function, a number of behavioral configuration options are available.

Configuration

Configuration methods in Mermaid version 8.6.0 have been updated, to learn more[click here].

What follows are config instructions for older versions

These are the default options which can be overridden with the initialization call like so: Example 1:

mermaid.initialize({
  flowchart:{
    htmlLabels: false
  }
});

Example 2:

<script>
  var config = {
    startOnLoad:true,
    flowchart:{
      useMaxWidth:true,
      htmlLabels:true,
      curve:'cardinal',
    },

    securityLevel:'loose',
  };
  mermaid.initialize(config);
</script>

A summary of all options and their defaults is found here. A description of each option follows below.

theme

theme , the CSS style sheet

Parameter	Description	Type	Required	Values
Theme	Built in Themes	String	Optional	Values include, default, forest, dark, neutral, null

**Notes:**To disable any pre-defined mermaid theme, use "null".

 "theme": "forest",
 "themeCSS": ".node rect { fill: red; }"

fontFamily

Parameter	Description	Type	Required	Values
fontFamily	specifies the font to be used in the rendered diagrams	String	Required	Verdana, Arial, Trebuchet MS,

**notes: Default value is \"trebuchet ms\".

logLevel

Parameter	Description	Type	Required	Values
logLevel	This option decides the amount of logging to be used.	String	Required	1, 2, 3, 4, 5

Notes:

debug: 1.
info: 2.
warn: 3.
error: 4.
fatal: 5(default).

securityLevel

Parameter	Description	Type	Required	Values
securitylevel	Level of trust for parsed diagram	String	Required	Strict, Loose, antiscript

**Notes:

strict: (default) tags in text are encoded, click functionality is disabeled
loose: tags in text are allowed, click functionality is enabled
antiscript: html tags in text are allowed, (only script element is removed), click functionality is enabled

startOnLoad

Parameter	Description	Type	Required	Values
startOnLoad	Dictates whether mermaind starts on Page load	Boolean	Required	True, False

Notes: Default value: true

arrowMarkerAbsolute

Parameter	Description	Type	Required	Values
arrowMarkerAbsolute	Controls whether or arrow markers in html code are absolute paths or anchors	Boolean	Required	True, False

Notes**: This matters if you are using base tag settings.

Default value: false.

secure

This option controls which currentConfig keys are considered secure and can only be changed via call to mermaidAPI.initialize. Calls to mermaidAPI.reinitialize cannot make changes to the secure keys in the current currentConfig. This prevents malicious graph directives from overriding a site's default security.

flowchart

The object containing configurations specific for flowcharts

diagramPadding

Parameter	Description	Type	Required	Values
diagramPadding	amount of padding around the diagram as a whole	Integer	Required	Any Positive Value

**Notes:**The amount of padding around the diagram as a whole so that embedded diagrams have margins, expressed in pixels Default value: 8.

htmlLabels

Parameter	Description	Type	Required	Values
htmlLabels	Flag for setting whether or not a html tag should be used for rendering labels on the edges.	Boolean	Required	True, False

Notes: Default value: true.

nodeSpacing

Parameter	Description	Type	Required	Values
nodeSpacing	Defines the spacing between nodes on the same level	Integer	Required	Any positive Numbers

Notes: Pertains to horizontal spacing for TB (top to bottom) or BT (bottom to top) graphs, and the vertical spacing for LR as well as RL graphs. Default value 50.

rankSpacing

Parameter	Description	Type	Required	Values
rankSpacing	Defines the spacing between nodes on different levels	Integer	Required	Any Positive Numbers

**Notes: pertains to vertical spacing for TB (top to bottom) or BT (bottom to top), and the horizontal spacing for LR as well as RL graphs. **Default value 50**.

curve

Parameter	Description	Type	Required	Values
curve	Defines how mermaid renders curves for flowcharts.	String	Required	Basis, Linear, Cardinal

Notes: Default Vaue: Linear

sequence

The object containing configurations specific for sequence diagrams

activationWidth

widt of the activation rect Default value 10.

diagramMarginX

Parameter	Description	Type	Required	Values
diagramMarginX	margin to the right and left of the sequence diagram	Integer	Required	Any Positive Values

Notes: Default value 50.

diagramMarginY

Parameter	Description	Type	Required	Values
diagramMarginY	Margin to the over and under the sequence diagram	Integer	Required	Any Positive Values

Notes: Default value 10.

actorMargin

Parameter	Description	Type	Required	Values
actorMargin	Margin between actors.	Integer	Required	Any Positive Value

Notes: Default value 50.

width

Parameter	Description	Type	Required	Values
width	Width of actor boxes	Integer	Required	Any Positive Value

Notes: Default value 150.

height

Parameter	Description	Type	Required	Values
height	Height of actor boxes	Integer	Required	Any Positive Value

Notes: Default value 65..

boxMargin

Parameter	Description	Type	Required	Values
boxMargin	Margin around loop boxes	Integer	Required	Any Positive Value

Notes:

Default value 10.

boxTextMargin

Parameter	Description	Type	Required	Values
boxTextMargin	margin around the text in loop/alt/opt boxes	Integer	Required	Any Positive Value

Notes:

Default value 5.

noteMargin

Parameter	Description	Type	Required	Values
noteMargin	margin around notes.	Integer	Required	Any Positive Value

Notes:

Default value 10.

messageMargin

Parameter	Description	Type	Required	Values
messageMargin	Space between messages.	Integer	Required	Any Positive Value

Notes:

Space between messages. Default value 35.

messageAlign

Parameter	Description	Type	Required	Values
messageAlign	Multiline message alignment	Integer	Required	left, center, right

**Notes:**center default

mirrorActors

Parameter	Description	Type	Required	Values
mirrorActors	mirror actors under diagram.	Boolean	Required	True, False

Notes:

Default value true.

bottomMarginAdj

Parameter	Description	Type	Required	Values
bottomMarginAdj	Prolongs the edge of the diagram downwards.	Integer	Required	Any Positive Value

**Notes:**Depending on css styling this might need adjustment. Default value 1.

useMaxWidth

Parameter	Description	Type	Required	Values
useMaxWidth	See Notes	Boolean	Required	True, False

Notes: when this flag is set to true, the height and width is set to 100% and is then scaling with the available space. If set to false, the absolute space required is used. Default value: True.

rightAngles

Parameter	Description	Type	Required	Values
rightAngles	display curve arrows as right angles	Boolean	Required	True, False

Notes:

This will display arrows that start and begin at the same node as right angles, rather than a curve Default value false.

showSequenceNumbers

Parameter	Description	Type	Required	Values
showSequenceNumbers	This will show the node numbers	Boolean	Required	True, False

Notes: Default value false.

actorFontSize

Parameter	Description	Type	Required	Values
actorFontSize	This sets the font size of the actor's description	Integer	Require	Any Positive Value

Notes: Default value 14..

actorFontFamily

Parameter	Description	Type	Required	Values
actorFontFamily	This sets the font family of the actor's description	3	4	Open-Sans, Sans-Serif

Notes: Default value "Open-Sans", "sans-serif".

actorFontWeight

This sets the font weight of the actor's description **Default value 400.

noteFontSize

Parameter	Description	Type	Required	Values
noteFontSize	This sets the font size of actor-attached notes.	Integer	Required	Any Positive Value

Notes: Default value 14..

noteFontFamily

Parameter	Description	Type	Required	Values
noteFontFamily	This sets the font family of actor-attached notes.	String	Required	trebuchet ms, verdana, arial

Notes: **Default value: trebuchet ms **.

noteFontWeight

This sets the font weight of the note's description **Default value 400.

noteAlign

Parameter	Description	Type	Required	Values
noteAlign	This sets the text alignment of actor-attached notes.	string	required	left, center, right

Notes: Default value center.

messageFontSize

Parameter	Description	Type	Required	Values
messageFontSize	This sets the font size of actor messages.	Integer	Required	Any Positive Number

Notes: Default value 16.

messageFontFamily

Parameter	Description	Type	Required	Values
messageFontFamily	This sets the font family of actor messages.	String	Required	trebuchet ms", verdana, aria

Notes: Default value:"trebuchet ms.

messageFontWeight

This sets the font weight of the message's description **Default value 400.

wrap

This sets the auto-wrap state for the diagram **Default value false.

wrapPadding

This sets the auto-wrap padding for the diagram (sides only) **Default value 10.

labelBoxWidth

This sets the width of the loop-box (loop, alt, opt, par) **Default value 50.

labelBoxHeight

This sets the height of the loop-box (loop, alt, opt, par) **Default value 20.

gantt

The object containing configurations specific for gantt diagrams*

titleTopMargin

Parameter	Description	Type	Required	Values
titleTopMargin	Margin top for the text over the gantt diagram	Integer	Required	Any Positive Value

Notes: Default value 25.

barHeight

Parameter	Description	Type	Required	Values
barHeight	The height of the bars in the graph	Integer	Required	Any Positive Value

Notes: Default value 20.

barGap

Parameter	Description	Type	Required	Values
barGap	The margin between the different activities in the gantt diagram.	Integer	Optional	Any Positive Value

Notes: Default value 4.

topPadding

Parameter	Description	Type	Required	Values
topPadding	Margin between title and gantt diagram and between axis and gantt diagram.	Integer	Required	Any Positive Value

Notes: Default value 50.

leftPadding

Parameter	Description	Type	Required	Values
leftPadding	The space allocated for the section name to the left of the activities.	Integer	Required	Any Positive Value

Notes: Default value 75.

gridLineStartPadding

Parameter	Description	Type	Required	Values
gridLineStartPadding	Vertical starting position of the grid lines.	Integer	Required	Any Positive Value

Notes: Default value 35.

Parameter	Description	Type	Required	Values
fontSize	Font size	Integer	Required	Any Positive Value

fontFamily

Parameter	Description	Type	Required	Values
fontFamily	font Family	string	required	"Open-Sans", "sans-serif"

Notes:

Default value '"Open-Sans", "sans-serif"'.

numberSectionStyles

Parameter	Description	Type	Required	Values
numberSectionStyles	The number of alternating section styles	Integer	4	Any Positive Value

Notes: Default value 4.

axisFormat

Parameter	Description	Type	Required	Values
axisFormat	Datetime format of the axis.	3	Required	Date in yy-mm-dd

Notes:

This might need adjustment to match your locale and preferences Default value '%Y-%m-%d'.

journey

The object containing configurations specific for sequence diagrams

diagramMarginX

Parameter	Description	Type	Required	Values
diagramMarginX	margin to the right and left of the sequence diagram	Integer	Required	Any Positive Value

Notes: Default value 50.

diagramMarginY

Parameter	Description	Type	Required	Values
diagramMarginY	margin to the over and under the sequence diagram.	Integer	Required	Any Positive Value

Notes: Default value 10..

actorMargin

Parameter	Description	Type	Required	Values
actorMargin	Margin between actors.	Integer	Required	Any Positive Value

Notes: Default value 50.

width

Parameter	Description	Type	Required	Values
width	Width of actor boxes	Integer	Required	Any Positive Value

Notes: Default value 150.

height

Parameter	Description	Type	Required	Values
height	Height of actor boxes	Integer	Required	Any Positive Value

Notes: Default value 65.

boxMargin

Parameter	Description	Type	Required	Values
boxMargin	Margin around loop boxes	Integer	Required	Any Positive Value

Notes: Default value 10.

boxTextMargin

Parameter	Description	Type	Required	Values
boxTextMargin	margin around the text in loop/alt/opt boxes	Integer	Required	Any Positive Value

Notes:

noteMargin

Parameter	Description	Type	Required	Values
noteMargin	margin around notes.	Integer	Required	Any Positive Value

Notes: Default value 10.

messageMargin

Parameter	Description	Type	Required	Values
messageMargin	Space between messages.	Integer	Required	Any Positive Value

Notes:

Space between messages. Default value 35.

messageAlign

Parameter	Description	Type	Required	Values
messageAlign	Multiline message alignment	3	4	left, center, right

**Notes:**default:center**

bottomMarginAdj

Parameter	Description	Type	Required	Values
bottomMarginAdj	Prolongs the edge of the diagram downwards.	Integer	4	Any Positive Value

**Notes:**Depending on css styling this might need adjustment. Default value 1.

useMaxWidth

Parameter	Description	Type	Required	Values
useMaxWidth	See notes	Boolean	4	True, False

**Notes:**when this flag is set the height and width is set to 100% and is then scaling with the available space if not the absolute space required is used.

Default value true.

rightAngles

Parameter	Description	Type	Required	Values
rightAngles	Curved Arrows become Right Angles,	3	4	True, False

**Notes:**This will display arrows that start and begin at the same node as right angles, rather than a curves Default value false.

er

The object containing configurations specific for entity relationship diagrams

diagramPadding

Parameter	Description	Type	Required	Values
diagramPadding	amount of padding around the diagram as a whole	Integer	Required	Any Positive Value

**Notes:**The amount of padding around the diagram as a whole so that embedded diagrams have margins, expressed in pixels Default value: 20.

layoutDirection

Parameter	Description	Type	Required	Values
layoutDirection	Directional bias for layout of entities.	String	Required	"TB", "BT","LR","RL"

Notes: 'TB' for Top-Bottom, 'BT'for Bottom-Top, 'LR' for Left-Right, or 'RL' for Right to Left. T = top, B = bottom, L = left, and R = right. **Default value: TB **.

minEntityWidth

Parameter	Description	Type	Required	Values
minEntityWidth	The mimimum width of an entity box,	Integer	Required	Any Positive Value

**Notes:**expressed in pixels Default value: 100.

minEntityHeight

Parameter	Description	Type	Required	Values
minEntityHeight	The minimum height of an entity box,	Integer	4	Any Positive Value

**Notes:**expressed in pixels **Default value: 75 **

entityPadding

Parameter	Description	Type	Required	Values
entityPadding	minimum internal padding betweentext in box and box borders	Integer	4	Any Positive Value

**Notes:**The minimum internal padding betweentext in an entity box and the enclosing box borders, expressed in pixels. **Default value: 15 **

stroke

Parameter	Description	Type	Required	Values
stroke	Stroke color of box edges and lines	String	4	Any recognized color

**Default value: gray **

fill

Parameter	Description	Type	Required	Values
fill	Fill color of entity boxes	String	4	Any recognized color

Notes: Default value:'honeydew'

useMaxWidth

Parameter	Description	Type	Required	Values
useMaxWidth	See Notes	Boolean	Required	true, false

Notes: When this flag is set to true, the diagram width is locked to 100% and scaled based on available space. If set to false, the diagram reserves its absolute width. Default value: true.

render

Function that renders an svg with a graph from a chart definition. Usage example below.

mermaidAPI.initialize({
     startOnLoad:true
 });
 $(function(){
     const graphDefinition = 'graph TB\na-->b';
     const cb = function(svgGraph){
         console.log(svgGraph);
     };
     mermaidAPI.render('id1',graphDefinition,cb);
 });

Parameters

id the id of the element to be rendered
_txt the graph definition
cb callback which is called after rendering is finished with the svg code as inparam.
container selector to element in which a div with the graph temporarily will be inserted. In one is provided a hidden div will be inserted in the body of the page instead. The element will be removed when rendering is completed.

mermaidAPI configuration defaults


<script>
  var config = {
    theme:'default',
    logLevel:'fatal',
    securityLevel:'strict',
    startOnLoad:true,
    arrowMarkerAbsolute:false,

    er:{
      diagramPadding:20,
      layoutDirection:'TB',
      minEntityWidth:100,
      minEntityHeight:75,
      entityPadding:15,
      stroke:'gray',
      fill:'honeydew',
      fontSize:12,
      useMaxWidth:true,
    },
    flowchart:{
      diagramPadding:8,
      htmlLabels:true,
      curve:'linear',
    },
    sequence:{
      diagramMarginX:50,
      diagramMarginY:10,
      actorMargin:50,
      width:150,
      height:65,
      boxMargin:10,
      boxTextMargin:5,
      noteMargin:10,
      messageMargin:35,
      messageAlign:'center',
      mirrorActors:true,
      bottomMarginAdj:1,
      useMaxWidth:true,
      rightAngles:false,
      showSequenceNumbers:false,
    },
    gantt:{
      titleTopMargin:25,
      barHeight:20,
      barGap:4,
      topPadding:50,
      leftPadding:75,
      gridLineStartPadding:35,
      fontSize:11,
      fontFamily:'"Open-Sans", "sans-serif"',
      numberSectionStyles:4,
      axisFormat:'%Y-%m-%d',
    }
  };
  mermaid.initialize(config);
</script>

setSiteConfig

Function	Description	Type	Values
setSiteConfig	Sets the siteConfig to desired values	Put Request	Any Values, except ones in secure array

Notes: Sets the siteConfig. The siteConfig is a protected configuration for repeat use. Calls to reset() will reset the currentConfig to siteConfig. Calls to reset(configApi.defaultConfig) will reset siteConfig and currentConfig to the defaultConfig Note: currentConfig is set in this function

*Default value: At default, will mirror Global Config**

Parameters

conf the base currentConfig to use as siteConfig

Returns any the siteConfig

getSiteConfig

Function	Description	Type	Values
setSiteConfig	Returns the current siteConfig base configuration	Get Request	Returns Any Values in siteConfig

Notes: Returns any values in siteConfig.

Returns any

setConfig

Function	Description	Type	Values
setSiteConfig	Sets the siteConfig to desired values	Put Request	Any Values, except ones in secure array

Notes: Sets the currentConfig. The parameter conf is sanitized based on the siteConfig.secure keys. Any values found in conf with key found in siteConfig.secure will be replaced with the corresponding siteConfig value.

Parameters

conf the potential currentConfig

Returns any the currentConfig merged with the sanitized conf

getConfig

Function	Description	Type	Return Values
getConfig	Obtains the currentConfig	Get Request	Any Values from currentConfig

Notes: Returns any the currentConfig

Returns any the currentConfig

sanitize

Function	Description	Type	Values
sanitize	Sets the siteConfig to desired values.	Put Request	None

Ensures options parameter does not attempt to override siteConfig secure keys Note: modifies options in-place

Parameters

options the potential setConfig parameter

reset

Function	Description	Type	Required	Values
reset	Resets currentConfig to conf	Put Request	Required	None

Parameter	Description	Type	Required	Values
conf	base set of values, which currentConfig coul be reset to.	Dictionary	Required	Any Values, with respect to the secure Array

*Notes : (default: current siteConfig ) (optional, default getSiteConfig())

Parameters

conf the base currentConfig to reset to (default: current siteConfig ) (optional, default getSiteConfig())

33 KiB Raw Blame History

mermaidAPI

Configuration

What follows are config instructions for older versions

theme

fontFamily

logLevel

securityLevel

startOnLoad

arrowMarkerAbsolute

Notes**: This matters if you are using base tag settings.

secure

flowchart

diagramPadding

htmlLabels

nodeSpacing

rankSpacing

curve

sequence

activationWidth

diagramMarginX

diagramMarginY

actorMargin

width

height

boxMargin

boxTextMargin

noteMargin

messageMargin

messageAlign

mirrorActors

bottomMarginAdj

useMaxWidth

rightAngles

showSequenceNumbers

actorFontSize

actorFontFamily

actorFontWeight

noteFontSize

noteFontFamily

noteFontWeight

noteAlign

messageFontSize

messageFontFamily

messageFontWeight

wrap

wrapPadding

labelBoxWidth

labelBoxHeight

gantt

titleTopMargin

titleTopMargin

barHeight

barGap

topPadding

leftPadding

gridLineStartPadding

fontSize

fontFamily

numberSectionStyles

axisFormat

journey

diagramMarginX

diagramMarginY

actorMargin

width

height

boxMargin

boxTextMargin

noteMargin

messageMargin

messageAlign

bottomMarginAdj

useMaxWidth

rightAngles

er

diagramPadding

layoutDirection

minEntityWidth

minEntityHeight

33 KiB

Raw Blame History