GitHub/mermaid
1
0
Fork 0
mirror of https://github.com/mermaid-js/mermaid.git synced 2025-01-28 07:03:17 +08:00
Code Issues Projects Releases Wiki Activity

Merge pull request #1560 from NeilCuzon/release/8.6.0

Browse Source 
Edited Release/8.6.0
This commit is contained in:
Knut Sveidqvist 2020-07-21 12:56:38 +02:00 committed by GitHub
commit 0f575907c7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 191 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/8.6.0_docs.md
View File

@ -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)

4
docs/CHANGELOG.md
View File

@ -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)*
\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*

4
docs/README.md
View File

@ -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/)

2
docs/breakingChanges.md
View File

@ -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

1
docs/classDiagram.md
View File

@ -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

2
docs/development.md
View File

@ -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).

35
docs/directives.md
View File

@ -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}%%|

4
docs/faq.md
View File

@ -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)

8
docs/n00b-gettingStarted.md
View File

@ -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)

65
docs/n00b-overview.md
View File

@ -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

32
docs/n00b-syntaxReference.md
View File

@ -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 \<div class=mermaid> tag.
like so :
```
<div class="mermaid">
graph LR
A --- B
B-->C[fa:fa-ban forbidden]
B-->D(fa:fa-spinner);
</div>
```
## 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)

88
docs/usage.md
View File

@ -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
<script src="mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>
<script src="https://cdn.jsdelivr.net/npm/mermaid@8.6.0/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>
```
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
<div class="mermaid">
CHART DEFINITION GOES HERE
graph LR
A --- B
B-->C[fa:fa-ban forbidden]
B-->D(fa:fa-spinner);
</div>
```
@ -53,9 +65,51 @@ Would end up like this:
</div>
```
## Simple full example:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
</head>
<body>
<div class="mermaid">
graph LR
A --- B
B-->C[fa:fa-ban forbidden]
B-->D(fa:fa-spinner);
</div>
<script src="https://cdn.jsdelivr.net/npm/mermaid@8.6.0/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>
</body>
</html>
```
## 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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
</head>
<body>
<div class="mermaid">
graph LR
A --- B
B-->C[fa:fa-ban forbidden]
B-->D(fa:fa-spinner);
</div>
<script src="mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>
</body>
</html>
```
### Labels out of bounds

2
docs/user-journey.md
View File

@ -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:

9
src/config.js
View File

@ -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|