![omahs](/assets/img/avatar_default.png)
* fix typos * fix typo * fix typo * fix typo * fix typos * fix typos * fix typos * fix typos * fix typos * fix typo * fix typo * chore: Update docs --------- Co-authored-by: Sidharth Vinod <sidharthv96@gmail.com>
9.6 KiB
Warning
THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
Please edit the corresponding file in /packages/mermaid/src/docs/config/directives.md.
Directives
Warning
Directives are deprecated from v<MERMAID_RELEASE_VERSION>. Please use the
config
key in frontmatter to pass configuration. See Configuration for more details.
Directives
Directives give a diagram author the capability to alter the appearance of a diagram before rendering by changing the applied configuration.
The significance of having directives is that you have them available while writing the diagram, and can modify the default global and diagram-specific configurations. So, directives are applied on top of the default configuration. The beauty of directives is that you can use them to alter configuration settings for a specific diagram, i.e. at an individual level.
While directives allow you to change most of the default configuration settings, there are some that are not available, for security reasons. Also, you have the option to define the set of configurations that you wish to allow diagram authors to override with directives.
Types of Directives options
Mermaid basically supports two types of configuration options to be overridden by directives.
-
General/Top Level configurations : These are the configurations that are available and applied to all the diagram. Some of the most important top-level configurations are:
- theme
- fontFamily
- logLevel
- securityLevel
- startOnLoad
- secure
-
Diagram-specific configurations : These are the configurations that are available and applied to a specific diagram. For each diagram there are specific configuration that will alter how that particular diagram looks and behaves. For example,
mirrorActors
is a configuration that is specific to theSequenceDiagram
and alters whether the actors are mirrored or not. So this config is available only for theSequenceDiagram
type.
NOTE: Not all configuration options are listed here. To get hold of all the configuration options, please refer to the defaultConfig.ts in the source code.
Note
We plan to publish a complete list of top-level configurations & diagram-specific configurations with their possible values in the docs soon.
Declaring directives
Now that we have defined the types of configurations that are available, we can learn how to declare directives.
A directive always starts and ends with %%
signs with directive text in between, like %% {directive_text} %%
.
Here the structure of a directive text is like a nested key-value pair map or a JSON object with root being init. Where all the general configurations are defined in the top level, and all the diagram specific configurations are defined one level deeper with diagram type as key/root for that section.
The following code snippet shows the structure of a directive:
%%{
init: {
"theme": "dark",
"fontFamily": "monospace",
"logLevel": "info",
"flowchart": {
"htmlLabels": true,
"curve": "linear"
},
"sequence": {
"mirrorActors": true
}
}
}%%
You can also define the directives in a single line, like this:
%%{init: { **insert configuration options here** } }%%
For example, the following code snippet:
%%{init: { "sequence": { "mirrorActors":false }}}%%
Notes: The JSON object that is passed as {argument} must be valid key value pairs and encased in quotation marks or it will be ignored. Valid Key Value pairs can be found in config.
Example with a simple graph:
%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%%
graph LR
A-->B
%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%%
graph LR
A-->B
Here the directive declaration will set the logLevel
to debug
and the theme
to dark
for a rendered mermaid diagram, changing the appearance of the diagram itself.
Note: You can use 'init' or 'initialize' as both are acceptable as init directives. Also note that %%init%%
and %%initialize%%
directives will be grouped together after they are parsed.
%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
%%{initialize: { 'logLevel': 'fatal', "theme":'dark', 'startOnLoad': true } }%%
...
%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
%%{initialize: { 'logLevel': 'fatal', "theme":'dark', 'startOnLoad': true } }%%
...
For example, parsing the above generates a single %%init%%
JSON object below, combining the two directives and carrying over the last value given for loglevel
:
{
"logLevel": "fatal",
"theme": "dark",
"startOnLoad": true
}
This will then be sent to mermaid.initialize(...)
for rendering.
Directive Examples
Now that the concept of directives has been explained, let us see some more examples of directive usage:
Changing theme via directive
The following code snippet changes theme
to forest
:
%%{init: { "theme": "forest" } }%%
Possible theme values are: default
, base
, dark
, forest
and neutral
.
Default Value is default
.
Example:
%%{init: { "theme": "forest" } }%%
graph TD
A(Forest) --> B[/Another/]
A --> C[End]
subgraph section
B
C
end
%%{init: { "theme": "forest" } }%%
graph TD
A(Forest) --> B[/Another/]
A --> C[End]
subgraph section
B
C
end
Changing fontFamily via directive
The following code snippet changes fontFamily to Trebuchet MS, Verdana, Arial, Sans-Serif:
%%{init: { "fontFamily": "Trebuchet MS, Verdana, Arial, Sans-Serif" } }%%
Example:
%%{init: { "fontFamily": "Trebuchet MS, Verdana, Arial, Sans-Serif" } }%%
graph TD
A(Forest) --> B[/Another/]
A --> C[End]
subgraph section
B
C
end
%%{init: { "fontFamily": "Trebuchet MS, Verdana, Arial, Sans-Serif" } }%%
graph TD
A(Forest) --> B[/Another/]
A --> C[End]
subgraph section
B
C
end
Changing logLevel via directive
The following code snippet changes logLevel
to 2
:
%%{init: { "logLevel": 2 } }%%
Possible logLevel
values are:
1
for debug,2
for info3
for warn4
for error5
for only fatal errors
Default Value is 5
.
Example:
%%{init: { "logLevel": 2 } }%%
graph TD
A(Forest) --> B[/Another/]
A --> C[End]
subgraph section
B
C
end
%%{init: { "logLevel": 2 } }%%
graph TD
A(Forest) --> B[/Another/]
A --> C[End]
subgraph section
B
C
end
Changing flowchart config via directive
Some common flowchart configurations are:
- htmlLabels: true/false
- curve: linear/curve
- diagramPadding: number
- useMaxWidth: number
For a complete list of flowchart configurations, see defaultConfig.ts in the source code. Soon we plan to publish a complete list of all diagram-specific configurations updated in the docs.
The following code snippet changes flowchart config:
%%{init: { "flowchart": { "htmlLabels": true, "curve": "linear" } } }%%
Here we are overriding only the flowchart config, and not the general config, setting htmlLabels
to true
and curve
to linear
.
%%{init: { "flowchart": { "htmlLabels": true, "curve": "linear" } } }%%
graph TD
A(Forest) --> B[/Another/]
A --> C[End]
subgraph section
B
C
end
%%{init: { "flowchart": { "htmlLabels": true, "curve": "linear" } } }%%
graph TD
A(Forest) --> B[/Another/]
A --> C[End]
subgraph section
B
C
end
Changing Sequence diagram config via directive
Some common sequence diagram configurations are:
- width: number
- height: number
- messageAlign: left, center, right
- mirrorActors: boolean
- useMaxWidth: boolean
- rightAngles: boolean
- showSequenceNumbers: boolean
- wrap: boolean
For a complete list of sequence diagram configurations, see defaultConfig.ts in the source code. Soon we plan to publish a complete list of all diagram-specific configurations updated in the docs.
So, wrap
by default has a value of false
for sequence diagrams.
Let us see an example:
sequenceDiagram
Alice->Bob: Hello Bob, how are you?
Bob->Alice: Fine, how did your mother like the book I suggested? And did you catch the new book about alien invasion?
Alice->Bob: Good.
Bob->Alice: Cool
sequenceDiagram
Alice->Bob: Hello Bob, how are you?
Bob->Alice: Fine, how did your mother like the book I suggested? And did you catch the new book about alien invasion?
Alice->Bob: Good.
Bob->Alice: Cool
Now let us enable wrap for sequence diagrams.
The following code snippet changes sequence diagram config for wrap
to true
:
%%{init: { "sequence": { "wrap": true} } }%%
By applying that snippet to the diagram above, wrap
will be enabled:
%%{init: { "sequence": { "wrap": true, "width":300 } } }%%
sequenceDiagram
Alice->Bob: Hello Bob, how are you?
Bob->Alice: Fine, how did your mother like the book I suggested? And did you catch the new book about alien invasion?
Alice->Bob: Good.
Bob->Alice: Cool
%%{init: { "sequence": { "wrap": true, "width":300 } } }%%
sequenceDiagram
Alice->Bob: Hello Bob, how are you?
Bob->Alice: Fine, how did your mother like the book I suggested? And did you catch the new book about alien invasion?
Alice->Bob: Good.
Bob->Alice: Cool