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