diff --git a/docs/8.6.0_docs.md b/docs/8.6.0_docs.md index 5918964ab..483fc314e 100644 --- a/docs/8.6.0_docs.md +++ b/docs/8.6.0_docs.md @@ -1,6 +1,6 @@ # Version 8.6.0 Changes -**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](./8.6.0_docs.md) +**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/8.6.0_docs.md) ## [New Mermaid Live-Editor Beta](https://mermaid-js.github.io/docs/mermaid-live-editor-beta/#/edit/eyJjb2RlIjoiJSV7aW5pdDoge1widGhlbWVcIjogXCJmb3Jlc3RcIiwgXCJsb2dMZXZlbFwiOiAxIH19JSVcbmdyYXBoIFREXG4gIEFbQ2hyaXN0bWFzXSAtLT58R2V0IG1vbmV5fCBCKEdvIHNob3BwaW5nKVxuICBCIC0tPiBDe0xldCBtZSB0aGlua31cbiAgQyAtLT58T25lfCBEW0xhcHRvcF1cbiAgQyAtLT58VHdvfCBFW2lQaG9uZV1cbiAgQyAtLT58VGhyZWV8IEZbZmE6ZmEtY2FyIENhcl1cblx0XHQiLCJtZXJtYWlkIjp7InRoZW1lIjoiZGFyayJ9fQ) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index f5d1bd860..4fcbb9e66 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,5 +1,7 @@ # Change Log +**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/CHANGELOG.md) + ## [Unreleased](https://github.com/knsv/mermaid/tree/HEAD) [Full Changelog](https://github.com/knsv/mermaid/compare/8.1.0...HEAD) @@ -856,4 +858,4 @@ ## [0.1.0](https://github.com/knsv/mermaid/tree/0.1.0) (2014-11-16) -\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)* \ No newline at end of file +\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)* diff --git a/docs/README.md b/docs/README.md index 6c4ae2c4d..50313a886 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,7 +5,7 @@ [![Join the chat at https://gitter.im/knsv/mermaid](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/knsv/mermaid?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ![banner](./img/header.png) -**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](./README.md) +**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/README.md) **Mermaid was nominated and won the JS Open Source Awards (2019) in the category "The most exciting use of technology"!!! Thanks to all involved, people committing pull requests, people answering questions and special thanks to Tyler Long who is helping me maintain the project.** @@ -24,7 +24,7 @@ For a more detailed introduction to mermaid, look to the [Beginner's Guide](http You should also Check out the list of [Integrations and Usages of Mermaid](./integrations.md) -You can also watch some popular mermaid tutorials. +You can also watch some popular mermaid tutorials on the [mermaid Overview](./n00b-overview.md) ## [CDN](https://unpkg.com/mermaid/) diff --git a/docs/breakingChanges.md b/docs/breakingChanges.md index 21206dc6d..27e4f2bdf 100644 --- a/docs/breakingChanges.md +++ b/docs/breakingChanges.md @@ -1,5 +1,5 @@ # Breaking changes - +**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/breakingChanges.md) ### Breaking changes from history version to latest version: ## #1 diff --git a/docs/classDiagram.md b/docs/classDiagram.md index 3972132b0..ebf0787ab 100644 --- a/docs/classDiagram.md +++ b/docs/classDiagram.md @@ -1,4 +1,5 @@ # Class diagrams +**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/classDiagram.md) > "In software engineering, a class diagram in the Unified Modeling Language (UML) is a type of static structure diagram that describes the structure of a system by showing the system's classes, their attributes, operations (or methods), and the relationships among objects." Wikipedia diff --git a/docs/development.md b/docs/development.md index 1a26f91e8..b4de72489 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,6 +1,6 @@ # Development - +**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/development.md) ## Updating the documentation Please continue writing documentation at [mermaid-js/mermaid/docs](https://github.com/mermaid-js/mermaid/tree/develop/docs). diff --git a/docs/directives.md b/docs/directives.md index e11f832be..985026d01 100644 --- a/docs/directives.md +++ b/docs/directives.md @@ -1,11 +1,26 @@ ## Directives **Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](./directives.md) -### Directives were added in [Version 8.6.0](/8.6.0_docs.md) -#### Init directives -With this version, directives are supported. Technically there are two flavors of directive: init/initialize and everything else. The init/initialize directive is parsed early in the flow enough to be able to re-initialize mermaid with a new configuration object. Example: +## Directives were added in [Version 8.6.0](/8.6.0_docs.md). Please Read it for more information. +## Directives +With this version, directives are supported. Directives are divided in two sets, by priority. the first set, containing 'init' or 'initialize' directives take priority. While the other set, containing all other kinds of directives are considered only after 'init' and the graph-type declared. + +#### Init + + +| Parameter | Description |Type | Required | Values| +| --- | --- | --- | --- | --- | +| init | modifies configurations| Directive| Optional | Any parameters not included in the secure array| + +**Notes:** + +init would be an argument-directive: %%{init: { **insert argument here**}}%% + +The json object that is passed as {**argument** } must be valid, quoted json or it will be ignored. + +The init/initialize directive is parsed early in the flow, enough to be able to re-initialize mermaid with a new configuration object. Example: ``` %%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%% graph > @@ -14,7 +29,7 @@ A-->B will set the `logLevel` to `debug` and the `theme` to `dark` for a flowchart diagram. -Note: init or initialize are both acceptable as init directives. Also note that init directives are coalesced. This means: +Note: 'init' or 'initialize' are both acceptable as init directives. Also note that init directives are coalesced. This means: ``` %%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%% @@ -33,10 +48,11 @@ will result an init object looking like this: ``` to be sent to `mermaid.initialize(...)` + #### Other directives -The other flavor of directive is everything else. In this category are any directives that follow the graph type declaration. Essentially, these directives will not be processed early in the flow like the init directive. Each individual graph type will handle these directives. As an example: +In this category are any directives that follow the graph type declaration. Essentially, these directives will not be processed early in the flow like the init directive. Each individual graph type will handle these directives. As an example: ``` %%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%% @@ -45,15 +61,20 @@ sequenceDiagram Alice->>Bob: Hi Bob Bob->>Alice: Hi Alice ``` - +## Chronology This will set the `logLevel` to `debug` and `theme` to `dark` for a sequence diagram. Then, during processing, the config for the sequence diagram is set by the `config` directive. This directive is handled in the `sequenceDb.js`. In this example, the fontFamily, fontSize, and fontWeight are all set for this sequence diagram. #### Backwards Compatibility -Init directives and any other non-multiline directives should be backwards compatible because they will be treated as comments in prior versions of mermaid-js. +Init directives and any other non-multiline directives should be backwards compatible, because they will be treated as comments in prior versions of mermaid-js. Multiline directives, however, will pose an issue and will render an error. This is unavoidable. ### Wrapping The `%%{wrap}%%` directive and the inline `wrap:` text hint have also been added for sequence diagrams. This has been explained in my previous comments and has not materially changed. + +# Wrap +| Parameter | Description |Type | Required | Values| +| --- | --- | --- | --- | --- | +| wrap | a callable text-wrap function| Directive| Optional | %%{wrap}%%| diff --git a/docs/faq.md b/docs/faq.md index c6924b3c2..f7fc5e26d 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,3 +1,7 @@ +Frequently Asked Questions: + +**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/faq.md) + 1. [How to add title to flowchart?](https://github.com/knsv/mermaid/issues/556#issuecomment-363182217) 1. [How to specify custom CSS file?](https://github.com/mermaidjs/mermaid.cli/pull/24#issuecomment-373402785) 1. [How to fix tooltip misplacement issue?](https://github.com/knsv/mermaid/issues/542#issuecomment-3343564621) diff --git a/docs/n00b-gettingStarted.md b/docs/n00b-gettingStarted.md index 594a4d00c..f5d4880f5 100644 --- a/docs/n00b-gettingStarted.md +++ b/docs/n00b-gettingStarted.md @@ -4,11 +4,11 @@ Creating diagrams and charts using mermaid code is simple. But how is the code turned into a diagram in a web page? This is done with the use of a mermaid renderer. -Thankfully the mermaid renderer is very accessible, in essence it is a piece of javascript that can be called. +The mermaid renderer is very accessible, in essence it is a piece of javascript that can be called. Most web browsers, such as Firefox, Chrome and Safari, can render mermaid, Internet Explorer however cannot. The web browser also needs access to the online mermaid renderer which it downloads from https://cdn.jsdelivr.net/npm/mermaid -# For beginners, there are three relatively easy ways you can use mermaid: +## For beginners, there are three relatively easy ways you can use mermaid: 1. Using the mermaid [live editor](https://mermaid-js.github.io/mermaid-live-editor/) 2. Using one of the many mermaid plugins 3. Calling mermaid renderer with HTML, deployed in a friendly browser. @@ -30,12 +30,12 @@ It is also an easier way to develop diagrams. You can also click "Copy Markdown" ![Flowchart](./img/liveEditorOptions.png) -The `Mermaid configuration` is for controlling mermaid behaviour. An easy introduction to mermaid configuration is found in the [Advanced usage](n00b-advanced.md) section. A complete configuration reference cataloguing default values is found on the [mermaidAPI](mermaidAPI.md) page. +The `Mermaid configuration` is for controlling mermaid behaviour. An easy introduction to mermaid configuration is found in the [Advanced usage](n00b-advanced.md) section. A complete configuration reference cataloguing default values is found on the [mermaidAPI](https://mermaid-js.github.io/mermaid/#/Setup) page. ## 2. Using mermaid plugins: -Thanks to the growing popularity of mermaid, many plugins already exist which incorporate a mermaid renderer. An extensive list can be found [here](integrations.md). +Thanks to the growing popularity of mermaid, many plugins already exist which incorporate a mermaid renderer. An extensive list can be found [here](./integrations.md). One example in the list is the [Atlassian Confluence mermaid plugin](https://marketplace.atlassian.com/apps/1214124/mermaid-plugin-for-confluence?hosting=server&tab=overview) diff --git a/docs/n00b-overview.md b/docs/n00b-overview.md index 83b5653b1..96e4e7b99 100644 --- a/docs/n00b-overview.md +++ b/docs/n00b-overview.md @@ -1,8 +1,27 @@ -# Overview for n00bs +# Overview for Beginners +**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/n00b-overview.md) -mermaid is a tool that aims to make diagrams and flowcharts for documentation, easier. +## There is no explanation like a Good Diagram -with mermaid, diagrams can be created through comments like this in a script: +A picture is worth a thousand words, a good diagram would be worth more. There is no disputing that they are indeed very useful. Yet very few people use them, even fewer still do so, for documentation. + +mermaid aims to change that. + +## Creating and Maintaining Diagrams should not be an expensive and frustrating process. + +Anyone who has used Visio, or (God Forbid) Excel to make a Gantt Chart, knows how hard it is to make, edit and maintain good visualizations. + +In an environment of constantly changing information , diagrams/charts become obsolete/inaccurate very fast. This hobbles the information transfer and productivity in teams. + +# Doc Rot kills Diagrams + +The fast setting Doc-Rot in diagrams makes it quite hard to rationalize taking hours in a desktop application, to produce a diagram that you would need to recreate again the following week in order to account for updates and changes in the app you are documenting. Yet that is often the reality for diagrams and charts and the people who make them. + +mermaid seeks to change that. mermaid is a javascript based tool that utilizes a markdown inspired syntax to generate documentation, which is actually quicker, less complicated and more convenient than most traditional diagramming software. This is a relatively straightforward solution to a major hurdle in software teams. + +# The primary objective of mermaid is to help in addressing the problem of Doc Rot. + +With mermaid, diagrams can be created through comments like this in a script: ``` graph TD @@ -15,15 +34,41 @@ And they are rendered into this and made part of the documentation: ![Flowchart](./img/n00b-firstFlow.png) -Most of the similar visuals that you might need to create can be scripted in a similar way, with a varitety of different symbols and chart types available. -Since the diagram source is text based, it can be part of production scripts (and other pieces of code). So less time needs be spent on documenting as a separate task. +## Advantages of Using Mermaid -Comparing with Visio and similar applications, mermaid is a really fast way to create good visualizations. This is especially apparent when editing a complex visualisations, a process that usually takes hours in a desktop application, but only takes minutes (or even less if generation has been scripted) with mermaid. +- The Advantages of mermaid include its ease of generation, modification and rendering. +- The number of integrations that it has. +- It is a package that can be deployed to create -mermaid can potentially cut down the amount of time and effort spent on the process of creating diagrams, to a fraction of what you usually put in. -However, a lot of the mermaid documentation is geared to professional frontend developers, presuming a skill set which I simply do not have. +## Diagramming and charting is a gigantic waste of developer time, but not having diagrams ruins productivity. -If you need some basic instructions and introductions, here are a few good places to start: +mermaid can cut down the amount of time, effort and the learning curve that is associated with creating diagrams and charts, by a wide margin. -For information on how to use mermaid, click [here](https://mermaid-js.github.io/mermaid/#/n00b-gettingStarted), or you can try out the mermaid [live editor](https://mermaid-js.github.io/mermaid-live-editor/), alternatively, you could also view the [integrations and uses](https://github.com/mermaid-js/mermaid/blob/develop/docs/integrations.md) for mermaid. +Because, the text base for diagrams allows for it to be updated easily, it can also be made part of production scripts (and other pieces of code). So less time needs be spent on documenting, as a separate task. + + +## mermaid helps Documentation catch up with Development, in quickly changing projects. + +Being based on markdown, mermaid can be used, not only by accomplished front-end developers, but by most computer savvy people to render simple diagrams, at much faster speeds. +In fact one can pick up the syntax for it quite easily from the examples given and there are many tutorials in the internet. + +## mermaid is for everyone. + +For information on how to use mermaid, click [here](https://mermaid-js.github.io/mermaid/#/n00b-gettingStarted). +You can try out the mermaid [live editor](https://mermaid-js.github.io/mermaid-live-editor/). +Alternatively, you could also view the [integrations and uses](https://mermaid-js.github.io/mermaid/#/./integrations). + +# For anyone who may need video tutorials, here is a list of beginner friendly introductions: + +https://www.youtube.com/watch?v=SQ9QmuTHuSI&t=438s + +https://www.youtube.com/watch?v=5RQqht3NNSE + +https://www.youtube.com/watch?v=7_2IroEs6Is&t=207s + +https://www.youtube.com/watch?v=9HZzKkAqrX8 + +https://www.youtube.com/watch?v=7_2IroEs6Is&t=207s + +https://www.youtube.com/watch?v=9HZzKkAqrX8 diff --git a/docs/n00b-syntaxReference.md b/docs/n00b-syntaxReference.md index cbc389ed0..d8cb5d4d1 100644 --- a/docs/n00b-syntaxReference.md +++ b/docs/n00b-syntaxReference.md @@ -1,6 +1,30 @@ -## Diagram syntax reference +## Diagram syntax +**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/n00b-syntaxReference.md) + +If you are new to mermaid, read the [Getting Started](n00b-gettingStarted.md) and [Overview](n00b-overview.md) sections, to learn the basics of mermaid. +Video Tutorials can be found at the bottom of the Overview Section. + +This section is a list of diagram types supported by mermaid. Below is a list of links to aricles that explain the syntax of the diagrams or charts that 0can be called. + +They also detail how diagrams can be defined, or described in the manner with which the diagram is to be rendered by the renderer. + +### The benefits of text based diagramming are its speed and modifiability. mermaid allows for easy maintenance and modification of diagrams. This means your diagrams will always be up to date and closely follow your code and improve your documentation. + +## mermaid tag: +These Diagram Definitions can be entered within a \
tag. +like so : +``` +
+ graph LR + A --- B + B-->C[fa:fa-ban forbidden] + B-->D(fa:fa-spinner); +
+``` +## mermaid Live Editor +These definitions can also be entered into the [mermaid live editor](https://mermaid-js.github.io/mermaid-live-editor), to render them immediately. +This would then offer -Having already [gotten started](n00b-gettingStarted.md), existing diagram syntax documentation was easy enough to follow even for a n00b like me.. - [Flowchart](flowchart.md) - [Sequence diagram](sequenceDiagram.md) @@ -8,4 +32,6 @@ Having already [gotten started](n00b-gettingStarted.md), existing diagram syntax - [State Diagram](stateDiagram.md) - [Gantt](gantt.md) - [Pie Chart](pie.md) - +- [Entity Relationship Diagram](entityRelationshipDiagram.md) +- [User Journey Diagram](user-journey.md) +- [Directives](directives.md) diff --git a/docs/usage.md b/docs/usage.md index 1e50060da..5f6039cbc 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,11 +1,20 @@ # Usage +**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/usage.md) ## Installation -### npm package +### npm package ``` -yarn add mermaid +1.You will need to isntall node v10 or 12, which would have npm. + +2. download yarn using npm. + +2. enter the following command: + yarn add mermaid + +3. You can then add mermaid as a dev dependency using this command: + yarn add --dev mermaid ``` ### CDN @@ -27,19 +36,22 @@ locate the graphs on the page and transform them to svg files. ### Include mermaid on your web page: ```html - - + + ``` Further down on your page mermaid will look for tags with `class="mermaid"`. From these tags mermaid will try to read the chart definiton and replace it with the svg chart. -### Define a chart like this: +### Define a chart like thi: ```html
- CHART DEFINITION GOES HERE + graph LR + A --- B + B-->C[fa:fa-ban forbidden] + B-->D(fa:fa-spinner);
``` @@ -53,9 +65,51 @@ Would end up like this:
``` +## Simple full example: + +```html + + + + + + +
+ graph LR + A --- B + B-->C[fa:fa-ban forbidden] + B-->D(fa:fa-spinner); +
+ + + + +``` +## Try it out, save this code as HTML and load it. + +### To enable click event and tags in nodes + +In version 8.2 a security improvement was introduced. A `securityLevel` configuration was introduced which sets the level of trust to be used on the parsed diagrams. + +* **true**: (default) tags in text are encoded, click functionality is disabled +* false: tags in text are allowed, click functionality is enabled + +⚠️ **Note** : This changes the default behaviour of mermaid so that after upgrade to 8.2, if the `securityLevel` is not configured, tags in flowcharts are encoded as tags and clicking is prohibited. + +If your application is taking resposibility for the diagram source security you can set the `securityLevel` accordingly. By doing this clicks and tags are again allowed. + +```javascript + mermaidAPI.initialize({ + securityLevel: 'loose' + }); +``` + +## Notes: An id attribute is also added to mermaid tags without one. -### To enable click event and tags in nodes +Mermaid can load multiple diagrams, in the same page. + +## To enable click event and tags in nodes: In version 8.2 a security improvement was introduced. A `securityLevel` configuration was introduced which sets the level of trust to be used on the parsed diagrams. @@ -72,26 +126,6 @@ If your application is taking resposibility for the diagram source security you }); ``` -### Simple full example: - -```html - - - - - - -
- graph LR - A --- B - B-->C[fa:fa-ban forbidden] - B-->D(fa:fa-spinner); -
- - - - -``` ### Labels out of bounds diff --git a/docs/user-journey.md b/docs/user-journey.md index a40af2acd..e466fd3b7 100644 --- a/docs/user-journey.md +++ b/docs/user-journey.md @@ -1,5 +1,5 @@ # User Journey Diagram - +**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/user-journey.md) > User journeys describe at a high level of detail exactly what steps different users take to complete a specific task within a system, application or website. This technique shows the current (as-is) user workflow, and reveals areas of improvement for the to-be workflow. (Wikipedia) Mermaid can render user journey diagrams: diff --git a/src/config.js b/src/config.js index f762f00ad..ba06c2146 100644 --- a/src/config.js +++ b/src/config.js @@ -856,17 +856,14 @@ const currentConfig = assignWithDepth({}, defaultConfig); /** *## setSiteConfig - *| Function | Description | Type | Values | *| --------- | ------------------- | ------- | ------------------ | *| setSiteConfig|Sets the siteConfig to desired values | Put Request | Any Values, except ones in secure array| - ***Notes:** *Sets the siteConfig. The siteConfig is a protected configuration for repeat use. Calls to reset() will reset *the currentConfig to siteConfig. Calls to reset(configApi.defaultConfig) will reset siteConfig and currentConfig *to the defaultConfig *Note: currentConfig is set in this function - **Default value: At default, will mirror Global Config** * @param conf - the base currentConfig to use as siteConfig * @returns {*} - the siteConfig @@ -883,7 +880,6 @@ export const setSiteConfig = conf => { *| Function | Description | Type | Values | *| --------- | ------------------- | ------- | ------------------ | *| setSiteConfig|Returns the current siteConfig base configuration | Get Request | Returns Any Values in siteConfig| - ***Notes**: *Returns **any** values in siteConfig. * @returns {*} @@ -896,8 +892,6 @@ export const getSiteConfig = () => { *| Function | Description | Type | Values | *| --------- | ------------------- | ------- | ------------------ | *| setSiteConfig|Sets the siteConfig to desired values | Put Request| Any Values, except ones in secure array| - - ***Notes**: *Sets the currentConfig. The parameter conf is sanitized based on the siteConfig.secure keys. Any *values found in conf with key found in siteConfig.secure will be replaced with the corresponding @@ -916,7 +910,6 @@ export const setConfig = conf => { *| Function | Description | Type | Return Values | *| --------- | ------------------- | ------- | ------------------ | *| getConfig |Obtains the currentConfig | Get Request | Any Values from currentConfig| - ***Notes**: *Returns **any** the currentConfig * @returns {*} - the currentConfig @@ -929,7 +922,6 @@ export const getConfig = () => { *| Function | Description | Type | Values | *| --------- | ------------------- | ------- | ------------------ | *| sanitize |Sets the siteConfig to desired values. | Put Request |None| - *Ensures options parameter does not attempt to override siteConfig secure keys *Note: modifies options in-place * @param options - the potential setConfig parameter @@ -949,7 +941,6 @@ export const sanitize = options => { }; /** *## reset - *| Function | Description | Type | Required | Values | *| --------- | ------------------- | ------- | -------- | ------------------ | *| reset|Resets currentConfig to conf| Put Request | Required | None|