9.9 KB343 lines
Blame
1> **Warning**
2>
3> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
4>
5> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/directives.md](../../packages/mermaid/src/docs/config/directives.md).
6
7# Directives
8
9> **Warning**
10> Directives are deprecated from v10.5.0. Please use the `config` key in frontmatter to pass configuration. See [Configuration](./configuration.md) for more details.
11
12## Directives
13
14Directives give a diagram author the capability to alter the appearance of a diagram before rendering by changing the applied configuration.
15
16The 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.
17
18While 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.
19
20## Types of Directives options
21
22Mermaid basically supports two types of configuration options to be overridden by directives.
23
241. _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:
25 - theme
26 - fontFamily
27 - logLevel
28 - securityLevel
29 - startOnLoad
30 - secure
31
322. _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.
33 For example, `mirrorActors` is a configuration that is specific to the `SequenceDiagram` and alters whether the actors are mirrored or not. So this config is available only for the `SequenceDiagram` type.
34
35**NOTE:** Not all configuration options are listed here. To get hold of all the configuration options, please refer to the [defaultConfig.ts](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/defaultConfig.ts) in the source code.
36
37> **Note**
38> We plan to publish a complete list of top-level configurations & diagram-specific configurations with their possible values in the docs soon.
39
40## Declaring directives
41
42Now that we have defined the types of configurations that are available, we can learn how to declare directives.
43A directive always starts and ends with `%%` signs with directive text in between, like `%% {directive_text} %%`.
44
45Here 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.
46
47The following code snippet shows the structure of a directive:
48
49```
50%%{
51 init: {
52 "theme": "dark",
53 "fontFamily": "monospace",
54 "logLevel": "info",
55 "htmlLabels": true,
56 "flowchart": {
57 "curve": "linear"
58 },
59 "sequence": {
60 "mirrorActors": true
61 }
62 }
63}%%
64```
65
66You can also define the directives in a single line, like this:
67
68```
69%%{init: { **insert configuration options here** } }%%
70```
71
72For example, the following code snippet:
73
74```
75%%{init: { "sequence": { "mirrorActors":false }}}%%
76```
77
78**Notes:**
79The JSON object that is passed as {**argument**} must be valid key value pairs and encased in quotation marks or it will be ignored.
80Valid Key Value pairs can be found in config.
81
82Example with a simple graph:
83
84```mermaid-example
85%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%%
86graph LR
87A-->B
88```
89
90```mermaid
91%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%%
92graph LR
93A-->B
94```
95
96Here 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.
97
98Note: 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.
99
100```mermaid-example
101%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
102%%{initialize: { 'logLevel': 'fatal', "theme":'dark', 'startOnLoad': true } }%%
103...
104```
105
106```mermaid
107%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
108%%{initialize: { 'logLevel': 'fatal', "theme":'dark', 'startOnLoad': true } }%%
109...
110```
111
112For example, parsing the above generates a single `%%init%%` JSON object below, combining the two directives and carrying over the last value given for `loglevel`:
113
114```json
115{
116 "logLevel": "fatal",
117 "theme": "dark",
118 "startOnLoad": true
119}
120```
121
122This will then be sent to `mermaid.initialize(...)` for rendering.
123
124## Directive Examples
125
126Now that the concept of directives has been explained, let us see some more examples of directive usage:
127
128### Changing theme via directive
129
130The following code snippet changes `theme` to `forest`:
131
132`%%{init: { "theme": "forest" } }%%`
133
134Possible theme values are: `default`, `base`, `dark`, `forest` and `neutral`.
135Default Value is `default`.
136
137Example:
138
139```mermaid-example
140%%{init: { "theme": "forest" } }%%
141graph TD
142A(Forest) --> B[/Another/]
143A --> C[End]
144 subgraph section
145 B
146 C
147 end
148
149```
150
151```mermaid
152%%{init: { "theme": "forest" } }%%
153graph TD
154A(Forest) --> B[/Another/]
155A --> C[End]
156 subgraph section
157 B
158 C
159 end
160
161```
162
163### Changing fontFamily via directive
164
165The following code snippet changes fontFamily to Trebuchet MS, Verdana, Arial, Sans-Serif:
166
167`%%{init: { "fontFamily": "Trebuchet MS, Verdana, Arial, Sans-Serif" } }%%`
168
169Example:
170
171```mermaid-example
172%%{init: { "fontFamily": "Trebuchet MS, Verdana, Arial, Sans-Serif" } }%%
173graph TD
174A(Forest) --> B[/Another/]
175A --> C[End]
176 subgraph section
177 B
178 C
179 end
180
181```
182
183```mermaid
184%%{init: { "fontFamily": "Trebuchet MS, Verdana, Arial, Sans-Serif" } }%%
185graph TD
186A(Forest) --> B[/Another/]
187A --> C[End]
188 subgraph section
189 B
190 C
191 end
192
193```
194
195### Changing logLevel via directive
196
197The following code snippet changes `logLevel` to `2`:
198
199`%%{init: { "logLevel": 2 } }%%`
200
201Possible `logLevel` values are:
202
203- `1` for _debug_,
204- `2` for _info_
205- `3` for _warn_
206- `4` for _error_
207- `5` for _only fatal errors_
208
209Default Value is `5`.
210
211Example:
212
213```mermaid-example
214%%{init: { "logLevel": 2 } }%%
215graph TD
216A(Forest) --> B[/Another/]
217A --> C[End]
218 subgraph section
219 B
220 C
221 end
222```
223
224```mermaid
225%%{init: { "logLevel": 2 } }%%
226graph TD
227A(Forest) --> B[/Another/]
228A --> C[End]
229 subgraph section
230 B
231 C
232 end
233```
234
235### Changing flowchart config via directive
236
237Some common flowchart configurations are:
238
239- ~~_htmlLabels_~~: Deprecated, [prefer setting this at the root level](/config/schema-docs/config#htmllabels).
240- _curve_: linear/curve
241- _diagramPadding_: number
242- _useMaxWidth_: number
243
244For a complete list of flowchart configurations, see [defaultConfig.ts](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/defaultConfig.ts) in the source code.
245_Soon we plan to publish a complete list of all diagram-specific configurations updated in the docs._
246
247The following code snippet changes flowchart config:
248
249```
250%%{init: { "htmlLabels": true, "flowchart": { "curve": "linear" } } }%%
251```
252
253Here we are overriding only the flowchart config, and not the general config, setting `htmlLabels` to `true` and `curve` to `linear`.
254
255> **Warning**
256> **Deprecated:** `flowchart.htmlLabels` has been deprecated from (v\<MERMAID_RELEASE_VERSION>+). Use the global `htmlLabels` configuration instead. For example, instead of `"flowchart": { "htmlLabels": true }`, use `"htmlLabels": true` at the top level.
257
258```mermaid-example
259%%{init: { "flowchart": { "htmlLabels": true, "curve": "linear" } } }%%
260graph TD
261A(Forest) --> B[/Another/]
262A --> C[End]
263 subgraph section
264 B
265 C
266 end
267```
268
269```mermaid
270%%{init: { "flowchart": { "htmlLabels": true, "curve": "linear" } } }%%
271graph TD
272A(Forest) --> B[/Another/]
273A --> C[End]
274 subgraph section
275 B
276 C
277 end
278```
279
280### Changing Sequence diagram config via directive
281
282Some common sequence diagram configurations are:
283
284- _width_: number
285- _height_: number
286- _messageAlign_: left, center, right
287- _mirrorActors_: boolean
288- _useMaxWidth_: boolean
289- _rightAngles_: boolean
290- _showSequenceNumbers_: boolean
291- _wrap_: boolean
292
293For a complete list of sequence diagram configurations, see [defaultConfig.ts](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/defaultConfig.ts) in the source code.
294_Soon we plan to publish a complete list of all diagram-specific configurations updated in the docs._
295
296So, `wrap` by default has a value of `false` for sequence diagrams.
297
298Let us see an example:
299
300```mermaid-example
301sequenceDiagram
302
303Alice->Bob: Hello Bob, how are you?
304Bob->Alice: Fine, how did your mother like the book I suggested? And did you catch the new book about alien invasion?
305Alice->Bob: Good.
306Bob->Alice: Cool
307```
308
309```mermaid
310sequenceDiagram
311
312Alice->Bob: Hello Bob, how are you?
313Bob->Alice: Fine, how did your mother like the book I suggested? And did you catch the new book about alien invasion?
314Alice->Bob: Good.
315Bob->Alice: Cool
316```
317
318Now let us enable wrap for sequence diagrams.
319
320The following code snippet changes sequence diagram config for `wrap` to `true`:
321
322`%%{init: { "sequence": { "wrap": true} } }%%`
323
324By applying that snippet to the diagram above, `wrap` will be enabled:
325
326```mermaid-example
327%%{init: { "sequence": { "wrap": true, "width":300 } } }%%
328sequenceDiagram
329Alice->Bob: Hello Bob, how are you?
330Bob->Alice: Fine, how did your mother like the book I suggested? And did you catch the new book about alien invasion?
331Alice->Bob: Good.
332Bob->Alice: Cool
333```
334
335```mermaid
336%%{init: { "sequence": { "wrap": true, "width":300 } } }%%
337sequenceDiagram
338Alice->Bob: Hello Bob, how are you?
339Bob->Alice: Fine, how did your mother like the book I suggested? And did you catch the new book about alien invasion?
340Alice->Bob: Good.
341Bob->Alice: Cool
342```
343