mirrors
/
mermaid
mirror of https://github.com/mermaid-js/mermaid.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Fix Directives Documentation 

Signed-off-by: Adam Henley <adamazing@gmail.com>
This commit is contained in:
Adam Henley 2023-06-10 23:27:22 +12:00
parent 779acb1b72
commit d32d935c44
No known key found for this signature in database
GPG Key ID: 509ED10F5B23CDF6
2 changed files with 72 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
docs/config/directives.md
View File

@ -8,11 +8,11 @@
## Directives
Directives gives a diagram author the capability to alter the appearance of a diagram before rendering by changing the applied configuration.
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 configurations. The beauty of directives is that you can use them to alter configuration settings for a specific diagram, i.e. at an individual level.
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, that too for security reasons. Also, you do have the _option to define the set of configurations_ that you would allow to be available to the diagram author for overriding with help of directives.
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
@ -20,29 +20,29 @@ Mermaid basically supports two types of configuration options to be overridden b
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:
- theme
- fontFamily
- logLevel
- securityLevel
- startOnLoad
- secure
- theme
- fontFamily
- logLevel
- securityLevel
- startOnLoad
- secure
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.
For example, `mirrorActors` is a configuration that is specific to the `SequenceDiagram` and alter whether the actors are mirrored or not. So this config is available only for the `SequenceDiagram` type.
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.
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.
**NOTE:** These options listed here are not all the configuration options. 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.
**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.
> **Note**
> We plan to publish a complete list of top-level configurations & all the diagram specific configurations, with their possible values in the docs soon.
> 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 end `%%` sign with directive text in between, like `%% {directive_text} %%`.
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.
Following code snippet shows the structure of a directive:
The following code snippet shows the structure of a directive:
%%{
init: {
@ -61,14 +61,14 @@ Following code snippet shows the structure of a directive:
You can also define the directives in a single line, like this:
%%{init: { **insert argument here**}}%%
%%{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.
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:
@ -87,7 +87,7 @@ 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 acceptable as init directives. Also note that `%%init%%` and `%%initialize%%` directives will be grouped together after they are parsed. This means:
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.
```mermaid-example
%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
@ -101,7 +101,7 @@ Note: You can use 'init' or 'initialize' as both acceptable as init directives.
...
```
parsing the above generates a single `%%init%%` JSON object below, combining the two directives and carrying over the last value given for `loglevel`:
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`:
```json
{
@ -115,16 +115,15 @@ This will then be sent to `mermaid.initialize(...)` for rendering.
## Directive Examples
More directive examples for diagram specific configuration overrides
Now that the concept of directives has been explained, Let us see some more examples for directives usage:
Now that the concept of directives has been explained, let us see some more examples of directive usage:
### Changing Theme via directive
### Changing theme via directive
The following code snippet changes theme to forest:
The following code snippet changes `theme` to `forest`:
`%%{init: { "theme": "forest" } }%%`
Possible themes value are: `default`,`base`, `dark`, `forest` and `neutral`.
Possible theme values are: `default`,`base`, `dark`, `forest` and `neutral`.
Default Value is `default`.
Example:
@ -155,7 +154,7 @@ A --> C[End]
### Changing fontFamily via directive
The following code snippet changes fontFamily to rebuchet MS, Verdana, Arial, Sans-Serif:
The following code snippet changes fontFamily to Trebuchet MS, Verdana, Arial, Sans-Serif:
`%%{init: { "fontFamily": "Trebuchet MS, Verdana, Arial, Sans-Serif" } }%%`
@ -187,11 +186,11 @@ A --> C[End]
### Changing logLevel via directive
The following code snippet changes logLevel to 2:
The following code snippet changes `logLevel` to `2`:
`%%{init: { "logLevel": 2 } }%%`
Possible logLevel values are:
Possible `logLevel` values are:
- `1` for _debug_,
- `2` for _info_
@ -234,14 +233,14 @@ Some common flowchart configurations are:
- _diagramPadding_: number
- _useMaxWidth_: number
For 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.
_Soon we plan to publish a complete list all diagram specific configurations updated in the docs_
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.
_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 were are overriding only the flowchart config, and not the general config, where HtmlLabels is set to true and curve is set to linear.
Here we are overriding only the flowchart config, and not the general config, setting `htmlLabels` to `true` and `curve` to `linear`.
```mermaid-example
%%{init: { "flowchart": { "htmlLabels": true, "curve": "linear" } } }%%
@ -267,7 +266,7 @@ A --> C[End]
### Changing Sequence diagram config via directive
Some common sequence configurations are:
Some common sequence diagram configurations are:
- _width_: number
- _height_: number
@ -278,8 +277,8 @@ Some common sequence configurations are:
- _showSequenceNumbers_: boolean
- _wrap_: boolean
For complete list of sequence diagram configurations, see _defaultConfig.ts_ in the source code.
_Soon we plan to publish a complete list all diagram specific configurations updated in the docs_
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.
_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.
@ -289,7 +288,7 @@ Let us see an example:
sequenceDiagram
Alice->Bob: Hello Bob, how are you?
Bob->Alice: Fine, How did you mother like the book I suggested? And did you catch with the new book about alien invasion?
Bob->Alice: Fine, how did you mother like the book I suggested? And did you catch the new book about alien invasion?
Alice->Bob: Good.
Bob->Alice: Cool
```
@ -298,7 +297,7 @@ Bob->Alice: Cool
sequenceDiagram
Alice->Bob: Hello Bob, how are you?
Bob->Alice: Fine, How did you mother like the book I suggested? And did you catch with the new book about alien invasion?
Bob->Alice: Fine, how did you mother like the book I suggested? And did you catch the new book about alien invasion?
Alice->Bob: Good.
Bob->Alice: Cool
```
@ -309,13 +308,13 @@ The following code snippet changes sequence diagram config for `wrap` to `true`:
`%%{init: { "sequence": { "wrap": true} } }%%`
Using in the diagram above, the wrap will be enabled.
By applying that snippet to the diagram above, `wrap` will be enabled:
```mermaid-example
%%{init: { "sequence": { "wrap": true, "width":300 } } }%%
sequenceDiagram
Alice->Bob: Hello Bob, how are you?
Bob->Alice: Fine, How did you mother like the book I suggested? And did you catch with the new book about alien invasion?
Bob->Alice: Fine, how did you mother like the book I suggested? And did you catch the new book about alien invasion?
Alice->Bob: Good.
Bob->Alice: Cool
```
@ -324,7 +323,7 @@ Bob->Alice: Cool
%%{init: { "sequence": { "wrap": true, "width":300 } } }%%
sequenceDiagram
Alice->Bob: Hello Bob, how are you?
Bob->Alice: Fine, How did you mother like the book I suggested? And did you catch with the new book about alien invasion?
Bob->Alice: Fine, how did you mother like the book I suggested? And did you catch the new book about alien invasion?
Alice->Bob: Good.
Bob->Alice: Cool
```

71
packages/mermaid/src/docs/config/directives.md
View File

@ -2,11 +2,11 @@
## Directives
Directives gives a diagram author the capability to alter the appearance of a diagram before rendering by changing the applied configuration.
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 configurations. The beauty of directives is that you can use them to alter configuration settings for a specific diagram, i.e. at an individual level.
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, that too for security reasons. Also, you do have the _option to define the set of configurations_ that you would allow to be available to the diagram author for overriding with help of directives.
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
@ -14,30 +14,30 @@ Mermaid basically supports two types of configuration options to be overridden b
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:
- theme
- fontFamily
- logLevel
- securityLevel
- startOnLoad
- secure
- theme
- fontFamily
- logLevel
- securityLevel
- startOnLoad
- secure
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.
For example, `mirrorActors` is a configuration that is specific to the `SequenceDiagram` and alter whether the actors are mirrored or not. So this config is available only for the `SequenceDiagram` type.
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.
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.
**NOTE:** These options listed here are not all the configuration options. 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.
**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.
```note
We plan to publish a complete list of top-level configurations & all the diagram specific configurations, with their possible values in the docs soon.
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 end `%%` sign with directive text in between, like `%% {directive_text} %%`.
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.
Following code snippet shows the structure of a directive:
The following code snippet shows the structure of a directive:
```
%%{
@ -59,7 +59,7 @@ Following code snippet shows the structure of a directive:
You can also define the directives in a single line, like this:
```
%%{init: { **insert argument here**}}%%
%%{init: { **insert configuration options here** } }%%
```
For example, the following code snippet:
@ -69,7 +69,7 @@ For example, the following code snippet:
```
**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.
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:
@ -82,7 +82,7 @@ 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 acceptable as init directives. Also note that `%%init%%` and `%%initialize%%` directives will be grouped together after they are parsed. This means:
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.
```mermaid
%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
@ -90,7 +90,7 @@ Note: You can use 'init' or 'initialize' as both acceptable as init directives.
...
```
parsing the above generates a single `%%init%%` JSON object below, combining the two directives and carrying over the last value given for `loglevel`:
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`:
```json
{
@ -104,16 +104,15 @@ This will then be sent to `mermaid.initialize(...)` for rendering.
## Directive Examples
More directive examples for diagram specific configuration overrides
Now that the concept of directives has been explained, Let us see some more examples for directives usage:
Now that the concept of directives has been explained, let us see some more examples of directive usage:
### Changing Theme via directive
### Changing theme via directive
The following code snippet changes theme to forest:
The following code snippet changes `theme` to `forest`:
`%%{init: { "theme": "forest" } }%%`
Possible themes value are: `default`,`base`, `dark`, `forest` and `neutral`.
Possible theme values are: `default`,`base`, `dark`, `forest` and `neutral`.
Default Value is `default`.
Example:
@ -132,7 +131,7 @@ A --> C[End]
### Changing fontFamily via directive
The following code snippet changes fontFamily to rebuchet MS, Verdana, Arial, Sans-Serif:
The following code snippet changes fontFamily to Trebuchet MS, Verdana, Arial, Sans-Serif:
`%%{init: { "fontFamily": "Trebuchet MS, Verdana, Arial, Sans-Serif" } }%%`
@ -152,11 +151,11 @@ A --> C[End]
### Changing logLevel via directive
The following code snippet changes logLevel to 2:
The following code snippet changes `logLevel` to `2`:
`%%{init: { "logLevel": 2 } }%%`
Possible logLevel values are:
Possible `logLevel` values are:
- `1` for _debug_,
- `2` for _info_
@ -188,14 +187,14 @@ Some common flowchart configurations are:
- _diagramPadding_: number
- _useMaxWidth_: number
For 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.
_Soon we plan to publish a complete list all diagram specific configurations updated in the docs_
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.
_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 were are overriding only the flowchart config, and not the general config, where HtmlLabels is set to true and curve is set to linear.
Here we are overriding only the flowchart config, and not the general config, setting `htmlLabels` to `true` and `curve` to `linear`.
```mermaid-example
%%{init: { "flowchart": { "htmlLabels": true, "curve": "linear" } } }%%
@ -210,7 +209,7 @@ A --> C[End]
### Changing Sequence diagram config via directive
Some common sequence configurations are:
Some common sequence diagram configurations are:
- _width_: number
- _height_: number
@ -221,8 +220,8 @@ Some common sequence configurations are:
- _showSequenceNumbers_: boolean
- _wrap_: boolean
For complete list of sequence diagram configurations, see _defaultConfig.ts_ in the source code.
_Soon we plan to publish a complete list all diagram specific configurations updated in the docs_
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.
_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.
@ -232,7 +231,7 @@ Let us see an example:
sequenceDiagram
Alice->Bob: Hello Bob, how are you?
Bob->Alice: Fine, How did you mother like the book I suggested? And did you catch with the new book about alien invasion?
Bob->Alice: Fine, how did you mother like the book I suggested? And did you catch the new book about alien invasion?
Alice->Bob: Good.
Bob->Alice: Cool
```
@ -243,13 +242,13 @@ The following code snippet changes sequence diagram config for `wrap` to `true`:
`%%{init: { "sequence": { "wrap": true} } }%%`
Using in the diagram above, the wrap will be enabled.
By applying that snippet to the diagram above, `wrap` will be enabled:
```mermaid-example
%%{init: { "sequence": { "wrap": true, "width":300 } } }%%
sequenceDiagram
Alice->Bob: Hello Bob, how are you?
Bob->Alice: Fine, How did you mother like the book I suggested? And did you catch with the new book about alien invasion?
Bob->Alice: Fine, how did you mother like the book I suggested? And did you catch the new book about alien invasion?
Alice->Bob: Good.
Bob->Alice: Cool
```