| 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/8.6.0_docs.md](../../packages/mermaid/src/docs/config/8.6.0_docs.md). |
| 6 | |
| 7 | # Version 8.6.0 Changes |
| 8 | |
| 9 | ## [New Mermaid Live-Editor Beta](https://mermaid-js.github.io/docs/mermaid-live-editor-beta/#/edit/eyJjb2RlIjoiJSV7aW5pdDoge1widGhlbWVcIjogXCJmb3Jlc3RcIiwgXCJsb2dMZXZlbFwiOiAxIH19JSVcbmdyYXBoIFREXG4gIEFbQ2hyaXN0bWFzXSAtLT58R2V0IG1vbmV5fCBCKEdvIHNob3BwaW5nKVxuICBCIC0tPiBDe0xldCBtZSB0aGlua31cbiAgQyAtLT58T25lfCBEW0xhcHRvcF1cbiAgQyAtLT58VHdvfCBFW2lQaG9uZV1cbiAgQyAtLT58VGhyZWV8IEZbZmE6ZmEtY2FyIENhcl1cblx0XHQiLCJtZXJtYWlkIjp7InRoZW1lIjoiZGFyayJ9fQ) |
| 10 | |
| 11 | ## [CDN](https://www.jsdelivr.com/package/npm/mermaid) |
| 12 | |
| 13 | With version 8.6.0 comes the release of directives for mermaid, a new system for modifying configurations, with the aim of establishing centralized, sane defaults and simple implementation. |
| 14 | |
| 15 | `directives` allow for a single-use overwriting of `config`, as it has been discussed in [Configurations](../config/configuration.md). |
| 16 | This allows site Diagram Authors to instantiate temporary modifications to `config` through the use of [Directives](directives.md), which are parsed before rendering diagram definitions. This allows the Diagram Authors to alter the appearance of the diagrams. |
| 17 | |
| 18 | **A likely application for this is in the creation of diagrams/charts inside company/organizational webpages, that rely on mermaid for diagram and chart rendering.** |
| 19 | |
| 20 | the `init` directive is the main method of configuration for Site and Current Levels. |
| 21 | |
| 22 | The three levels of are Configuration, Global, Site and Current. |
| 23 | |
| 24 | | Level of Configuration | Description | |
| 25 | | ---------------------- | ----------------------------------- | |
| 26 | | Global Configuration | Default Mermaid Configurations | |
| 27 | | Site Configuration | Configurations made by site owner | |
| 28 | | Current Configuration | Configurations made by Implementors | |
| 29 | |
| 30 | # Limits to Modifying Configurations |
| 31 | |
| 32 | **secure Array** |
| 33 | |
| 34 | | Parameter | Description | Type | Required | Values | |
| 35 | | --------- | ------------------------------------------------ | ----- | -------- | -------------- | |
| 36 | | secure | Array of parameters excluded from init directive | Array | Required | Any parameters | |
| 37 | |
| 38 | The modifiable parts of the Configuration are limited by the secure array, which is an array of immutable parameters, this array can be expanded by site owners. |
| 39 | |
| 40 | **Notes**: secure arrays work like nesting dolls, with the Global Configurations’ secure array holding the default and immutable list of immutable parameters, or the smallest doll, to which site owners may add to, but implementors may not modify it. |
| 41 | |
| 42 | # Secure Arrays |
| 43 | |
| 44 | Site owners can add to the **secure** array using this command: |
| 45 | mermaidAPI.initialize( { startOnLoad: true, secure: \['parameter1', 'parameter2'] } ); |
| 46 | |
| 47 | Default values for the `secure array` consists of: \['secure', 'securityLevel', 'startOnLoad', 'maxTextSize']. These default values are immutable. |
| 48 | |
| 49 | Implementors can only modify configurations using directives, and cannot change the `secure` array. |
| 50 | |
| 51 | # Modifying Configurations and directives: |
| 52 | |
| 53 | The Two types of directives: are `init` (or `initialize`) and `wrap`. |
| 54 | |
| 55 | > **Note** |
| 56 | > All directives are enclosed in `%%{ }%%` |
| 57 | |
| 58 | Older versions of mermaid will not parse directives because `%%` will comment out the directive. This makes the update backwards-compatible. |
| 59 | |
| 60 | # Init |
| 61 | |
| 62 | `init`, or `initialize`: this directive gives the user the ability to overwrite and change the values for any configuration parameters not set in the secure array. |
| 63 | |
| 64 | | Parameter | Description | Type | Required | Values | |
| 65 | | --------- | ----------------------- | --------- | -------- | ----------------------------------------------- | |
| 66 | | init | modifies configurations | Directive | Optional | Any parameters not included in the secure array | |
| 67 | |
| 68 | > **Note** |
| 69 | > init would be an argument-directive: `%%{init: { **insert argument here**}}%%` |
| 70 | > |
| 71 | > The json object that is passed as {**argument** } must be valid, quoted json or it will be ignored. |
| 72 | > **for example**: |
| 73 | > |
| 74 | > `%%{init: {"theme": "default", "logLevel": 1 }}%%` |
| 75 | > |
| 76 | > Configurations that are passed through init cannot change the parameters in a secure array at a higher level. In the event of a collision, mermaid will give priority to secure arrays and parse the request without changing the values of those parameters in conflict. |
| 77 | > |
| 78 | > When deployed within code, init is called before the graph/diagram description. |
| 79 | |
| 80 | **for example**: |
| 81 | |
| 82 | ```mermaid-example |
| 83 | %%{init: {"theme": "default", "logLevel": 1 }}%% |
| 84 | graph LR |
| 85 | a-->b |
| 86 | b-->c |
| 87 | c-->d |
| 88 | d-->e |
| 89 | e-->f |
| 90 | f-->g |
| 91 | g--> |
| 92 | ``` |
| 93 | |
| 94 | ```mermaid |
| 95 | %%{init: {"theme": "default", "logLevel": 1 }}%% |
| 96 | graph LR |
| 97 | a-->b |
| 98 | b-->c |
| 99 | c-->d |
| 100 | d-->e |
| 101 | e-->f |
| 102 | f-->g |
| 103 | g--> |
| 104 | ``` |
| 105 | |
| 106 | # Wrap |
| 107 | |
| 108 | | Parameter | Description | Type | Required | Values | |
| 109 | | --------- | ----------------------------- | --------- | -------- | ---------- | |
| 110 | | wrap | a callable text-wrap function | Directive | Optional | %%{wrap}%% | |
| 111 | |
| 112 | > **Note** |
| 113 | > Wrap is a function that is currently only deployable for sequence diagrams. |
| 114 | > |
| 115 | > `Wrap respects a manually added <br>, so if the user wants to break up their text, they have full control over line breaks by adding <br> tags.` |
| 116 | > |
| 117 | > It is a non-argument directive and can be executed thusly: |
| 118 | > |
| 119 | > `%%{wrap}%%` . |
| 120 | |
| 121 | **An example of text wrapping in a sequence diagram**: |
| 122 | |
| 123 | !\[Image showing wrapped text]\(img/wrapped text.png) |
| 124 | |
| 125 | # Resetting Configurations: |
| 126 | |
| 127 | There are two more functions in the mermaidAPI that can be called by site owners: **reset** and **globalReset**. |
| 128 | |
| 129 | **reset**: resets the configuration to whatever the last configuration was. This can be done to undo more recent changes set from the last mermaidAPI.initialize({...}) configuration. |
| 130 | |
| 131 | **globalReset** will reset both the current configuration AND the site configuration back to the global defaults. |
| 132 | |
| 133 | **Notes**: Both `reset` and `globalReset` are only available to site owners, and as such implementors have to edit their configs using `init`. |
| 134 | |
| 135 | # Additional Utils to mermaid |
| 136 | |
| 137 | • **memoize**: simple caching for computationally expensive functions, reducing rendering time by about 90%. |
| 138 | |
| 139 | • **assignWithDepth** - an improvement on previous functions with config.js and `Object.assign`. The purpose of this function is to provide a sane mechanism for merging objects, similar to `object.assign`, but with depth. |
| 140 | |
| 141 | Example of **assignWithDepth**: |
| 142 | |
| 143 |  |
| 144 | |
| 145 | Example of **object.Assign**: |
| 146 | |
| 147 | !\[Image showing object.assign without depth]\(img/object.assign without depth.png) |
| 148 | |
| 149 | • **calculateTextDimensions**, **calculateTextWidth**， and **calculateTextHeight** - for measuring text dimensions, width and height. |
| 150 | |
| 151 | **Notes**: For more information on usage, parameters, and return info for these new functions take a look at the jsdocs for them in the utils package. |
| 152 | |
| 153 | # New API Requests Introduced in Version 8.6.0 |
| 154 | |
| 155 | ## setSiteConfig |
| 156 | |
| 157 | | Function | Description | Type | Values | Parameters | Returns | |
| 158 | | --------------- | ------------------------------------- | ----------- | --------------------------------------- | ---------- | ---------- | |
| 159 | | `setSiteConfig` | Sets the siteConfig to desired values | Put Request | Any Values, except ones in secure array | conf | siteConfig | |
| 160 | |
| 161 | > **Note** |
| 162 | > Sets the siteConfig. The siteConfig is a protected configuration for repeat use. Calls to reset() will reset |
| 163 | > the currentConfig to siteConfig. Calls to reset(configApi.defaultConfig) will reset siteConfig and currentConfig |
| 164 | > to the defaultConfig |
| 165 | > Note: currentConfig is set in this function。 |
| 166 | > Default value: will mirror Global Config |
| 167 | |
| 168 | ## getSiteConfig |
| 169 | |
| 170 | | Function | Description | Type | Values | |
| 171 | | --------------- | --------------------------------------------------- | ----------- | ---------------------------------- | |
| 172 | | `getSiteConfig` | Returns the current `siteConfig` base configuration | Get Request | Returns Any Values in `siteConfig` | |
| 173 | |
| 174 | > **Note** |
| 175 | > Returns any values in siteConfig. |
| 176 | |
| 177 | ## setConfig |
| 178 | |
| 179 | | Function | Description | Type | Values | Parameters | Returns | |
| 180 | | ----------- | ------------------------------------------ | ----------- | --------------------------------- | ---------- | ---------------------------------------------- | |
| 181 | | `setConfig` | Sets the `currentConfig` to desired values | Put Request | Any Values, those in secure array | conf | `currentConfig` merged with the sanitized conf | |
| 182 | |
| 183 | > **Note** |
| 184 | > Sets the currentConfig. The parameter conf is sanitized based on the siteConfig.secure keys. Any |
| 185 | > values found in conf with key found in siteConfig.secure will be replaced with the corresponding |
| 186 | > siteConfig value. |
| 187 | |
| 188 | ## getConfig |
| 189 | |
| 190 | | Function | Description | Type | Return Values | |
| 191 | | ----------- | --------------------------- | ----------- | ------------------------------- | |
| 192 | | `getConfig` | Obtains the `currentConfig` | Get Request | Any Values from `currentConfig` | |
| 193 | |
| 194 | > **Note** |
| 195 | > Returns any values in currentConfig. |
| 196 | |
| 197 | ## sanitize |
| 198 | |
| 199 | | Function | Description | Type | Values | |
| 200 | | ---------- | ---------------------------------------- | -------------- | ------ | |
| 201 | | `sanitize` | Sets the `siteConfig` to desired values. | Put Request(?) | None | |
| 202 | |
| 203 | > **Note** |
| 204 | > modifies options in-place |
| 205 | > Ensures options parameter does not attempt to override siteConfig secure keys. |
| 206 | |
| 207 | ## reset |
| 208 | |
| 209 | | Function | Description | Type | Required | Values | Parameter | |
| 210 | | -------- | ------------------------------ | ----------- | -------- | ------ | --------- | |
| 211 | | `reset` | Resets `currentConfig` to conf | Put Request | Required | None | conf | |
| 212 | |
| 213 | ## conf |
| 214 | |
| 215 | | Parameter | Description | Type | Required | Values | |
| 216 | | --------- | ------------------------------------------------------------ | ---------- | -------- | -------------------------------------------- | |
| 217 | | `conf` | base set of values, which `currentConfig` could be reset to. | Dictionary | Required | Any Values, with respect to the secure Array | |
| 218 | |
| 219 | > **Note** |
| 220 | > default: current siteConfig (optional, default `getSiteConfig()`) |
| 221 | |
| 222 | ## For more information, read [Setup](./setup/README.md). |
| 223 | |