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

Merge pull request #1596 from NeilCuzon/develop 

Changes to ReadMe.md, Addition of versionUpdates.md for version tracking.
This commit is contained in:
Knut Sveidqvist 2020-08-04 20:08:44 +02:00 committed by GitHub
parent 1b56a8b696 9b806f2690
commit 77be268a70
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 199 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
README.md
View File

@ -1,24 +1,52 @@
<!-- <Remove this in the future> -->
| :mega: :mega: :mega: |
| :----: |
| * If you're upgrading from a version __< v8.2.0__, there are [non-backward-compatible changes](http://mermaid-js.github.io/mermaid/#/usage?id=to-enable-click-event-and-tags-in-nodes) related to security issues. Default behaviour of the library might have changed for your implementation.|
<!-- </Remove this in the future> -->
# mermaid [![Build Status](https://travis-ci.org/mermaid-js/mermaid.svg?branch=master)](https://travis-ci.org/mermaid-js/mermaid) [![NPM](https://img.shields.io/npm/v/mermaid)](https://www.npmjs.com/package/mermaid) [![Coverage Status](https://coveralls.io/repos/github/mermaid-js/mermaid/badge.svg?branch=master)](https://coveralls.io/github/mermaid-js/mermaid?branch=master) [![Join our Slack!](https://img.shields.io/static/v1?message=join%20chat&color=9cf&logo=slack&label=slack)](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) [![This project is using Percy.io for visual regression testing.](https://percy.io/static/images/percy-badge.svg)](https://percy.io/Mermaid/mermaid)
<!-- <Main description> -->
__mermaid is a Javascript based diagramming and charting tool. It generates diagrams flowcharts and more, using markdown-inspired text for ease and speed.__
Check out the list of [Integrations and Usages of Mermaid](https://github.com/mermaid-js/mermaid/blob/develop/docs/integrations.md)
For more information and help in getting started, please view our [documentation](http://mermaid-js.github.io/mermaid/) and start simplifying yours. Alternatively, you can also play with our [live editor](https://mermaidjs.github.io/mermaid-live-editor/).
<!-- </Main description> -->
![banner](./img/header.png)
**Edit this Page** [![N|Solid](./docs/img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/README.md)
:trophy: **Mermaid was nominated and won the [JS Open Source Awards (2019)](https://osawards.com/javascript/#nominees) 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.**
## New diagram
This version comes with a new diagram type, user journey diagrams.
<!-- <Main description> -->
__mermaid is a Javascript based diagramming and charting tool that uses markdown-inspired text definitions and a renderer to create and modify complex diagrams. The main purpose of mermaid is to help Documentation catch up with Development.__
# Doc-Rot is a Catch-22 that Mermaid helps to solve.
### Diagramming and Documentation costs precious developer time and gets outdated quickly.
### But not having diagrams or Docs ruins productivity and hurts organizational learning.
## mermaid addresses this problem by cutting the time, effort and tooling that is required to create modifiable diagrams and charts, for smarter and more reusable content.**
The text definitions for mermaid 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 and laborious task.
## Even non-programmers can create diagrams through the [Mermaid Live Editor](https://github.com/mermaidjs/mermaid-live-editor).
## [mermaid Overview](./n00b-overview.md) has video tutorials.
## Use mermaid with your favorite applications, check out the list of [Integrations and Usages of Mermaid](./integrations.md)**
## For a more detailed introduction to mermaid and some of it's more basic uses, look to the [Beginner's Guide](https://mermaid-js.github.io/mermaid/#/n00b-overview) and [Usage](./usage.md).
## [CDN](https://unpkg.com/mermaid/)
## [Documentation](https://mermaidjs.github.io)
## [Contribution](https://github.com/mermaid-js/mermaid/blob/develop/CONTRIBUTING.md)
## Record of [Mermaid Version Changes](./versionUpdates.md).
# Version News: 8.7.0 Released with Updates to Theme Configuration
## [Version 8.7.0](./docs/theming.md) Mermaid comes out with a System for Dynamic and Integrated Diagram Theme Configuration.
## Mermaid comes out with [New Configuration Protocols in Version 8.6.0](./docs/8.6.0_docs.md)
## New diagrams in 8.4
@ -45,7 +73,6 @@ mermaidAPI.initialize({
});
```
For more information and help in getting started, please view our [documentation](http://mermaid-js.github.io/mermaid/) and start simplifying yours. Play with our [live editor](https://mermaidjs.github.io/mermaid-live-editor/) or jump straight to the [installation and usage](http://mermaid-js.github.io/mermaid/#/usage).
<!-- </Main description> -->
__The following are some examples of the diagrams, charts and graphs that can be made using mermaid and the Markdown-inspired text specific to it. Click here jump into the [text syntax](https://mermaid-js.github.io/mermaid/#/n00b-syntaxReference).__

83
docs/README.md
View File

@ -11,20 +11,22 @@
**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.**
# Doc-Rot is a Catch-22 that Mermaid helps to solve.
Mermaid is a tool that generates diagrams and charts, from markdown-inspired text definitions
### Diagramming and Documentation costs precious developer time and gets outdated quickly.
### But not having diagrams or Docs ruins productivity and hurts organizational learning.
This allows for simplified generation and updating of even the most complex diagrams and charts, while avoiding time-damanding and heavy tools like visio.
## mermaid addresses this problem by cutting the time, effort and tooling that is required to create modifiable diagrams and charts, for smarter and more reusable content.**
mermaid, is a simple markdown-inspired script language for generating charts from text-definitions, via javascript. As such, using it cuts the times it takes to create, modify and render diagrams.
The text definitions that create mermaid diagrams allows for easy updates, 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 and laborious task.
Even non-programmers can create diagrams through the [mermaid live editor](https://github.com/mermaidjs/mermaid-live-editor).
## Even non-programmers can create diagrams through the [Mermaid Live Editor](https://github.com/mermaidjs/mermaid-live-editor).
For a more detailed introduction to mermaid, look to the [Beginner's Guide](https://mermaid-js.github.io/mermaid/#/n00b-overview) section.
## You can watch some popular mermaid Live Editor tutorials on [mermaid Overview](./n00b-overview.md) for a quick intro.
You should also Check out the list of [Integrations and Usages of Mermaid](./integrations.md)
## To use mermaid with your favorite applications, check out the list of [Integrations and Usages of Mermaid](./integrations.md)**
You can also watch some popular mermaid tutorials on the [mermaid Overview](./n00b-overview.md)
## For a more detailed introduction to mermaid and some of it's more basic uses, look to the [Beginner's Guide](https://mermaid-js.github.io/mermaid/#/n00b-overview) and [Usage](./usage.md).
## [CDN](https://unpkg.com/mermaid/)
@ -32,47 +34,18 @@ You can also watch some popular mermaid tutorials on the [mermaid Overview](./n0
## [Contribution](https://github.com/mermaid-js/mermaid/blob/develop/CONTRIBUTING.md)
## [Recent Mermaid Versions](./versionUpdates.md).
# New in Version 8.6.0
# Most Recent Version News: Version 8.7.0
## [New and Expanded Mermaid Theme and Styling Configurations](./theming.md)
## [New Mermaid Live-Editor Beta](https://mermaid-js.github.io/docs/mermaid-live-editor-beta/#/edit/eyJjb2RlIjoiJSV7aW5pdDoge1widGhlbWVcIjogXCJmb3Jlc3RcIiwgXCJsb2dMZXZlbFwiOiAxIH19JSVcbmdyYXBoIFREXG4gIEFbQ2hyaXN0bWFzXSAtLT58R2V0IG1vbmV5fCBCKEdvIHNob3BwaW5nKVxuICBCIC0tPiBDe0xldCBtZSB0aGlua31cbiAgQyAtLT58T25lfCBEW0xhcHRvcF1cbiAgQyAtLT58VHdvfCBFW2lQaG9uZV1cbiAgQyAtLT58VGhyZWV8IEZbZmE6ZmEtY2FyIENhcl1cblx0XHQiLCJtZXJtYWlkIjp7InRoZW1lIjoiZGFyayJ9fQ)
## [New Configuration Protocols in version 8.6.0](./8.6.0_docs.md)
## New diagrams in 8.5
With version 8.5 there are some bug fixes and enhancements, plus a new diagram type, entity relationship diagrams.
![Image showing the new ER diagram type](./img/er.png)
## Special note regarding version 8.2
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.
## securityLevel
| Parameter | Description | Type | Required | Values |
| ------------- | --------------------------------- | ------ | -------- | ------------- |
| securitylevel | Level of trust for parsed diagram | String | Required | Strict, Loose |
\*\*Notes:
- **strict**: (**default**) tags in text are encoded, click functionality is disabeled
- **loose**: tags in text are allowed, click functionality is enabled
Closed issues:
⚠️ **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 responsibility 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'
});
```
## [Version Record](./versionUpdates.md)
**🖖 Keep a steady pulse: mermaid needs more Collaborators [#866](https://github.com/knsv/mermaid/issues/866)**
@ -196,7 +169,10 @@ journey
```
![Journey diagram](./img/user-journey.png)
## Installation
# Installation
## In depth guides and examples can be found in [Getting Started](./n00b-gettingStarted.md) and [Usage](./usage.md).
## It would also be helpful to learn more about mermaid's [Syntax](./n00b-syntaxReference.md).
### CDN
@ -212,33 +188,32 @@ Alternatively, you can also adjust the version number in the page itself.
Latest Version: https://unpkg.com/browse/mermaid@8.6.0/
## Incorporating mermaid to a website
to support mermaid on your website, all you have to do is add Mermaid’s JavaScript package
## Incorporating mermaid to a website
To support mermaid on your website, all you have to do is add Mermaid’s JavaScript package
```
1.You will need to isntall node v10 or 12, which would have npm
2. download yarn using npm.
2. enter the following command:
3. enter the following command:
yarn add mermaid
3. You can then add mermaid as a dev dependency using this command:
4. You can then add mermaid as a dev dependency using this command:
yarn add --dev mermaid
```
## To install mermaid without a bundler, one can use the script tag like so:
<script src="https://unpkg.com/mermaid/"></script>
## To deploy mermaid without a bundler, one can insert a `script` tag with an absolute address and a `mermaidAPI` call into the HTML like so:
```
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>
```
## doing so will command the mermaid parser to look for the `<div>` tags with `class="mermaid"` in your HTML Document. From these tags mermaid will try to read the diagram/chart definitons and render them as svg charts.
## it can then be followed by the diagram definitions as could be found in the [examples in the documentation](https://mermaid-js.github.io/mermaid/#/n00b-gettingStarted).
## Examples can be found in [Getting Started](./n00b-gettingStarted.md)
## 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 an svg chart.
## Sibling projects
# Sibling projects
- [mermaid live editor](https://github.com/mermaidjs/mermaid-live-editor)
- [mermaid CLI](https://github.com/mermaidjs/mermaid.cli)
- [mermaid webpack demo](https://github.com/mermaidjs/mermaid-webpack-demo)

1
docs/_sidebar.md
View File

@ -23,6 +23,7 @@
- [Development](development.md)
- [Configurations](Setup.md)
- [Mermaid Versions](versionUpdates.md)
- [Changelog](CHANGELOG.md)
- [Mermaid Versions](versionUpdate.md)

7
docs/directives.md
View File

@ -1,5 +1,7 @@
## Directives
**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](./directives.md)
**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)
## Directives were added in [Version 8.6.0](/8.6.0_docs.md). Please Read it for more information.
@ -72,9 +74,8 @@ Multiline directives, however, will pose an issue and will render an error. This
### 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}%%|

12
docs/n00b-overview.md
View File

@ -36,14 +36,16 @@ And they are rendered into this and made part of the documentation:
## Advantages of Using 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
- Ease of generation, modification and rendering.
- The number of integrations and plugins it has.
- It can be added to your or your company's website.
## Diagramming and charting is a gigantic waste of developer time, but not having diagrams ruins productivity.
## The catch-22 of Diagrams and Charts:
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.
**Diagramming and charting is a gigantic waste of developer time, but not having diagrams ruins productivity. **
mermaid solves this by cutting the time, effort and tooling that is required to create diagrams and charts.
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.

8
docs/usage.md
View File

@ -87,12 +87,14 @@ An id attribute is also added to mermaid tags without one.
Mermaid can load multiple diagrams, in the same page.
### Try it out, save this code as HTML and load it using any browser.(Please don't use Internet Explorer though.)
### Try it out, save this code as HTML and load it using any browser.(Except Internet Explorer, please don't use Internet Explorer.)
## To enable click event and tags in nodes
A `securityLevel` configuration has to first be cleared, `securityLevel` sets the level of trust for the parsed diagrams. This was introduce in version 8.2 as a security improvement, aimed at preventing malicious use.
A `securityLevel` configuration has to first be cleared, `securityLevel` sets the level of trust for the parsed diagrams and limits click functionality. This was introduce in version 8.2 as a security improvement, aimed at preventing malicious use.
**It is the site owner's resposniblity to discriminate between trustworthy and untrustworthy user-bases and we encourage the use of discretion.**
## securityLevel
@ -109,7 +111,7 @@ Mermaid can load multiple diagrams, in the same page.
⚠️ **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 you are taking resposibility for the diagram source security you can set the `securityLevel` to a value of your choosing . By doing this clicks and tags are again allowed.
**If you are taking resposibility for the diagram source security you can set the `securityLevel` to a value of your choosing . By doing this clicks and tags are allowed.**
## To chage `securityLevel` with `mermaidAPI.initialize`:

111
docs/versionUpdates.md Normal file
View File

@ -0,0 +1,111 @@
# Version News and Updates
**Edit this Page** [![N|Solid](./img/GitHub-Mark-32px.png)](https://github.com/mermaid-js/mermaid/blob/develop/docs/8.6.0_docs.md)
**This file will track the changes to mermaid and its evolution over time.**
## Here is the list of the newest versions in Descending Order, beginning from the latest version.
# [Version 8.7.0](./theming.md) brings with it a system for dynamic and integrated configuration of the diagram themes. The objective of this is to increase the customizability of mermaid and the ease of Styling, with the customization of themes through the `%%init%%` directive and `initialize` calls.
Themes follow and build upon the Levels of Configuration and employ `directives` to modify and create custom configurations, as they were introduced in Version [8.6.0](./8.6.0_docs.md).
**These Theming Configurations, similar to directives, will also be made applicable in the Live-Editor, for easier styling.
### Site-wide Themes
Site-wide themes are still declared via `initialize` by site owners.
Example of `Initalize` call setting `theme` to `base`:
```
mermaidAPI.initialize({
'securityLevel': 'loose', 'theme': 'base'
});
```
**Notes**: Only site owners can use the `mermaidAPI.initialize` call, to set values. Site-Users will have to use `%%init%%` to modify or create the theme for their diagrams.
## Themes at the Local or Current Level
When Generating a diagram using on a webpage that supports mermaid. It is also possible to override site-wide theme settings locally, for a specific diagram, using directives, as long as it is not prohibited by the `secure` array.
**Following is an example:
```
%%{init: {'theme':'base'}}%%
graph TD
a --> b
```
### Making a Custom Theme with `themeVariables`
The easiest way to make a custom theme is to start with the base theme, and just modify theme variables through `themeVariables`, via `%%init%%`.
| Parameter | Description | Type | Required | Objects contained |
| -------------- | ------------------------------------------------------------------ | ----- | -------- | ---------------------------------- |
| themeVariables | Array containing objects, modifiable with the `%%init%%` directive | Array | Required | primaryColor, lineColor, textColor |
### Here is an example of overriding `primaryColor` and giving everything a different look, using `%%init%%`.
```
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ff0000'}}}%%
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
B --> G[/Another/]
C ==>|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
subgraph section
C
D
E
F
G
end
```
**Notes:
Leaving it empty will set all variable values to default.
# [Version 8.6.0](./8.6.0_docs.md) introduces New Configuration Protocols and Directives and a Beta for the [New Mermaid Live-Editor](https://mermaid-js.github.io/docs/mermaid-live-editor-beta/#/edit/eyJjb2RlIjoiJSV7aW5pdDoge1widGhlbWVcIjogXCJmb3Jlc3RcIiwgXCJsb2dMZXZlbFwiOiAxIH19JSVcbmdyYXBoIFREXG4gIEFbQ2hyaXN0bWFzXSAtLT58R2V0IG1vbmV5fCBCKEdvIHNob3BwaW5nKVxuICBCIC0tPiBDe0xldCBtZSB0aGlua31cbiAgQyAtLT58T25lfCBEW0xhcHRvcF1cbiAgQyAtLT58VHdvfCBFW2lQaG9uZV1cbiAgQyAtLT58VGhyZWV8IEZbZmE6ZmEtY2FyIENhcl1cblx0XHQiLCJtZXJtYWlkIjp7InRoZW1lIjoiZGFyayJ9fQ)
**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.
directives allow for a diagram specific overriding of config, as it has been discussed in Configurations. This allows site users to input modifications to config alongside diagram definitions, when creating diagrams on a private webpage that supports mermaid.
# Version 8.5.0, introduces New diagrams
**New diagrams in 8.5**
With version 8.5 there are some bug fixes and enhancements, plus a new diagram type, entity relationship diagrams.
![Image showing the new ER diagram type](./img/er.png)
# Version 8.2.0, introduces a security improvement
A `securityLevel` configuration has to first be cleared, `securityLevel` sets the level of trust for the parsed diagrams and limits click functionality. This was introduce in version 8.2 as a security improvement, aimed at preventing malicious use.
## securityLevel
| Parameter | Description | Type | Required | Values |
| ------------- | --------------------------------- | ------ | -------- | ------------------------- |
| securitylevel | Level of trust for parsed diagram | String | Required | Strict, Loose, antiscript |
\*\*Notes:
- **strict**: (**default**) tags in text are encoded, click functionality is disabeled
- **loose**: tags in text are allowed, click functionality is enabled
- **antiscript**: html tags in text are allowed, (only script element is removed), 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 you are taking resposibility for the diagram source security you can set the `securityLevel` to a value of your choosing . By doing this clicks and tags are again allowed.
## To chage `securityLevel` with `mermaidAPI.initialize`:
```javascript
mermaidAPI.initialize({
securityLevel: 'loose'
});