diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 000000000..e69de29bb diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..6f99dd3f7 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,210 @@ +[![Build Status](https://travis-ci.org/knsv/mermaid.svg?branch=master)](https://travis-ci.org/knsv/mermaid) +[![Coverage Status](https://coveralls.io/repos/github/knsv/mermaid/badge.svg?branch=master)](https://coveralls.io/github/knsv/mermaid?branch=master) +[![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) + +# mermaid + +**🖖 Keep a steady pulse: mermaid needs more Collaborators [#866](https://github.com/knsv/mermaid/issues/866)** + +![banner](./img/header.png) + +Generation of diagrams and flowcharts from text in a similar manner as markdown. + +Ever wanted to simplify documentation and avoid heavy tools like Visio when explaining your code? + +This is why mermaid was born, a simple markdown-like script language for generating charts from text via javascript. + +**Mermaid was nomiated and won the JS Open Source Awards (2019) in the catory The most existing 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.** + +### Flowchart + +``` +graph TD; + A-->B; + A-->C; + B-->D; + C-->D; +``` +![Flowchart](./img/flow.png) + + +### Sequence diagram + +``` +sequenceDiagram + participant Alice + participant Bob + Alice->>John: Hello John, how are you? + loop Healthcheck + John->>John: Fight against hypochondria + end + Note right of John: Rational thoughts
prevail! + John-->>Alice: Great! + John->>Bob: How about you? + Bob-->>John: Jolly good! +``` +![Sequence diagram](./img/sequence.png) + + +### Gantt diagram + +``` +gantt +dateFormat YYYY-MM-DD +title Adding GANTT diagram to mermaid +excludes weekdays 2014-01-10 + +section A section +Completed task :done, des1, 2014-01-06,2014-01-08 +Active task :active, des2, 2014-01-09, 3d +Future task : des3, after des2, 5d +Future task2 : des4, after des3, 5d +``` +![Gantt diagram](./img/gantt.png) + + +### Class diagram - :exclamation: experimental + +``` +classDiagram +Class01 <|-- AveryLongClass : Cool +Class03 *-- Class04 +Class05 o-- Class06 +Class07 .. Class08 +Class09 --> C2 : Where am i? +Class09 --* C3 +Class09 --|> Class07 +Class07 : equals() +Class07 : Object[] elementData +Class01 : size() +Class01 : int chimp +Class01 : int gorilla +Class08 <--> C2: Cool label +``` +![Class diagram](./img/class.png) + + +### Git graph - :exclamation: experimental + +``` +gitGraph: +options +{ + "nodeSpacing": 150, + "nodeRadius": 10 +} +end +commit +branch newbranch +checkout newbranch +commit +commit +checkout master +commit +commit +merge newbranch + +``` + +![Git graph](./img/git.png) + + +## Installation + +### CDN + +``` +https://unpkg.com/mermaid@/dist/ +``` + +Replace `` with expected version number. + +Example: https://unpkg.com/mermaid@7.1.0/dist/ + +### Node.js + +``` +yarn add mermaid +``` + + +## Documentation + +https://mermaidjs.github.io + + +## Sibling projects + +- [mermaid CLI](https://github.com/mermaidjs/mermaid.cli) +- [mermaid live editor](https://github.com/mermaidjs/mermaid-live-editor) +- [mermaid webpack demo](https://github.com/mermaidjs/mermaid-webpack-demo) +- [mermaid Parcel demo](https://github.com/mermaidjs/mermaid-parcel-demo) + + +# Request for assistance + +Things are piling up and I have hard time keeping up. To remedy this +it would be great if we could form a core team of developers to cooperate +with the future development mermaid. + +As part of this team you would get write access to the repository and would +represent the project when answering questions and issues. + +Together we could continue the work with things like: +* adding more types of diagrams like mindmaps, ert diagrams etc +* improving existing diagrams + +Don't hesitate to contact me if you want to get involved. + + +# For contributors + +## Setup + + yarn install + + +## Build + + yarn build:watch + + +## Lint + + yarn lint + +We use [JavaScript Standard Style](https://github.com/feross/standard). +We recommend you installing [editor plugins](https://github.com/feross/standard#are-there-text-editor-plugins) so you can get real time lint result. + + +## Test + + yarn test + +Manual test in browser: + + open dist/index.html + + +## Release + +For those who have the permission to do so: + +Update version number in `package.json`. + + npm publish + +Command above generates files into the `dist` folder and publishes them to npmjs.org. + + +# Credits + +Many thanks to the [d3](http://d3js.org/) and [dagre-d3](https://github.com/cpettitt/dagre-d3) projects for providing the graphical layout and drawing libraries! + +Thanks also to the [js-sequence-diagram](http://bramp.github.io/js-sequence-diagrams) project for usage of the grammar for the sequence diagrams. Thanks to Jessica Peter for inspiration and starting point for gantt rendering. + +*Mermaid was created by Knut Sveidqvist for easier documentation.* + +*[Tyler Long](https://github.com/tylerlong) has became a collaborator since April 2017.* + +Here is the full list of the projects [contributors](https://github.com/knsv/mermaid/graphs/contributors). diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 000000000..e4be903f9 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,15 @@ +# Summary + +- [mermaid](README.md) +- [FAQ](faq.md) +- [Breaking changes](breakingChanges.md) +- [Usage](usage.md) +- [Flowchart](flowchart.md) +- [Sequence diagram](sequenceDiagram.md) +- [Gantt diagram](gantt.md) +- [mermaid CLI](mermaidCLI.md) +- [Demos](demos.md) +- [mermaidAPI](mermaidAPI.md) +- [Development](development.md) +- [Upgrading](upgrading.md) +- [Contribute to this website](https://github.com/mermaidjs/mermaid-gitbook) diff --git a/docs/_navbar.md b/docs/_navbar.md new file mode 100644 index 000000000..7156cccdb --- /dev/null +++ b/docs/_navbar.md @@ -0,0 +1,13 @@ +* Getting started + + * [Quick start](quickstart.md) + * [Writing more pages](more-pages.md) + * [Custom navbar](custom-navbar.md) + * [Cover page](cover.md) + +* Configuration + * [Configuration](configuration.md) + * [Themes](themes.md) + * [Using plugins](plugins.md) + * [Markdown configuration](markdown.md) + * [Language highlight](language-highlight.md) \ No newline at end of file diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 000000000..3bce972ff --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,26 @@ +- Getting started + + - [mermaid](README.md) + - [FAQ](faq.md) + - [Usage](usage.md) + - [Demos](demos.md) + - [mermaid CLI](mermaidCLI.md) + +- Diagrams + + - [Flowchart](flowchart.md) + - [Sequence diagram](sequenceDiagram.md) + - [Gantt](gantt.md) + +- Guide + + - [Development](development.md) + - [mermaidAPI](mermaidAPI.md) + - [Vue compatibility](vue.md) + - [CDN](cdn.md) + - [Offline Mode(PWA)](pwa.md) + - [Server-Side Rendering(SSR)](ssr.md) + - [Embed Files](embed-files.md) + +- [Awesome docsify](awesome.md) +- [Changelog](changelog.md) \ No newline at end of file diff --git a/docs/breakingChanges.md b/docs/breakingChanges.md new file mode 100644 index 000000000..21206dc6d --- /dev/null +++ b/docs/breakingChanges.md @@ -0,0 +1,51 @@ +# Breaking changes + +### Breaking changes from history version to latest version: + +## #1 + +```javascript +mermaid.initialize({ + sequenceDiagram:{ + ... + } +}) +``` + +has been changed to + +```javascript +mermaid.initialize({ + sequence:{ + ... + } +}) +``` + +## #2 + +In old versions you need to add CSS file to your HTML: + +```html + +``` + +or + +```html + +``` + +Now it is not needed to do so. And there are no more CSS files in distrubtion files. + +You just + +```javascript +mermaid.initialize({ + theme: 'forest' +}) +``` + +and it works like a charm. + +This is because now the CSS is inline with SVG for portability. diff --git a/docs/demos.md b/docs/demos.md new file mode 100644 index 000000000..a915c876d --- /dev/null +++ b/docs/demos.md @@ -0,0 +1,90 @@ +# Demos + + +## Basic sequence diagram + +```mermaid +sequenceDiagram + Alice ->> Bob: Hello Bob, how are you? + Bob-->>John: How about you John? + Bob--x Alice: I am good thanks! + Bob-x John: I am good thanks! + Note right of John: Bob thinks a long
long time, so long
that the text does
not fit on a row. + + Bob-->Alice: Checking with John... + Alice->John: Yes... John, how are you? +``` + + +## Basic flowchart + +```mermaid +graph LR + A[Square Rect] -- Link text --> B((Circle)) + A --> C(Round Rect) + B --> D{Rhombus} + C --> D +``` + + +## Larger flowchart with some styling + +```mermaid +graph TB + sq[Square shape] --> ci((Circle shape)) + + subgraph A subgraph + od>Odd shape]-- Two line
edge comment --> ro + di{Diamond with
line break} -.-> ro(Rounded
square
shape) + di==>ro2(Rounded square shape) + end + + %% Notice that no text in shape are added here instead that is appended further down + e --> od3>Really long text with linebreak
in an Odd shape] + + %% Comments after double percent signs + e((Inner / circle
and some odd
special characters)) --> f(,.?!+-*ز) + + cyr[Cyrillic]-->cyr2((Circle shape Начало)); + + classDef green fill:#9f6,stroke:#333,stroke-width:2px; + classDef orange fill:#f96,stroke:#333,stroke-width:4px; + class sq,e green + class di orange +``` + + +## Loops, alt and opt + +```mermaid +sequenceDiagram + loop Daily query + Alice->>Bob: Hello Bob, how are you? + alt is sick + Bob->>Alice: Not so good :( + else is well + Bob->>Alice: Feeling fresh like a daisy + end + + opt Extra response + Bob->>Alice: Thanks for asking + end + end +``` + + +## Message to self in loop + +```mermaid +sequenceDiagram + participant Alice + participant Bob + Alice->>John: Hello John, how are you? + loop Healthcheck + John->>John: Fight against hypochondria + end + Note right of John: Rational thoughts
prevail... + John-->>Alice: Great! + John->>Bob: How about you? + Bob-->>John: Jolly good! +``` diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 000000000..af2805afd --- /dev/null +++ b/docs/development.md @@ -0,0 +1,119 @@ +# Development + + +## Updating the documentation + +We write documention with GitBook. + +Please continue with the [mermaid-gitbook](https://github.com/mermaidjs/mermaid-gitbook) project. + + +## How to add a new diagram type + + +### Step 1: Grammar & Parsing + + +#### Grammar + +This would be to define a jison grammar for the new diagram type. That should start with a way to identify that the text in the mermaid tag is a diagram of that type. Create a new folder under diagrams for your new diagram type and a parser folder in it. This leads us to step 2. + +For instance: + +* the flowchart starts with the keyword graph. +* the sequence diagram starts with the keyword sequenceDiagram + + +#### Store data found during parsing + +There are some jison specific sub steps here where the parser stores the data encountered when parsing the diagram, this data is later used by the renderer. You can during the parsing call a object provided to the parser by the user of the parser. This object can be called during parsing for storing data. + +``` +statement + : 'participant' actor { $$='actor'; } + | signal { $$='signal'; } + | note_statement { $$='note'; } + | 'title' message { yy.setTitle($2); } + ; +``` + +In the extract of the grammar above, it is defined that a call to the setTitle method in the data object will be done when parsing and the title keyword is encountered. + +> **Info** Make sure that the `parseError` function for the parser is defined and calling `mermaidPAI.parseError`. This way a common way of detecting parse errors is provided for the end-user. + +For more info look in the example diagram type: + +The `yy` object has the following function: + +```javascript +exports.parseError = function(err, hash){ + mermaidAPI.parseError(err, hash) +}; +``` + +when parsing the `yy` object is initialized as per below: + +```javascript +var parser +parser = exampleParser.parser +parser.yy = db +``` + + +### Step 2: Rendering + +Write a renderer that given the data found during parsing renders the diagram. To look at an example look at sequendeRenderer.js rather then the flowchart renderer as this is a more generic example. + +Place the renderer in the diagram folder. + + +### Step 3: Detection of the new diagram type + +The second thing to do is to add the capability to detect the new new diagram to type to the detectType in utils.js. The detection should return a key for the new diagram type. + + +### Step 4: The final piece - triggering the rendering + +At this point when mermaid is trying to render the diagram, it will detect it as being of the new type but there will be no match when trying to render the diagram. To fix this add a new case in the switch statement in main.js:init this should match the diagram type returned from step #2. The code in this new case statement should call the renderer for the diagram type with the data found by the parser as an argument. + + +## Usage of the parser as a separate module + + +### Setup + +```javascript +var graph = require('./graphDb') +var flow = require('./parser/flow') +flow.parser.yy = graph +``` + + +### Parsing + +```javascript +flow.parser.parse(text) +``` + + +### Data extraction + +```javascript +graph.getDirection() +graph.getVertices() +graph.getEdges() +``` + +The parser is also exposed in the mermaid api by calling: + +```javascript +var parser = mermaid.getParser() +``` + +Note that the parse needs a graph object to store the data as per: + +```javascript +flow.parser.yy = graph +``` + +Look at `graphDb.js` for more details on that object. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000..038a3ae1d --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,8 @@ +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) +1. [How to specify gantt diagram xAxis format?](https://github.com/knsv/mermaid/issues/269#issuecomment-373229136) +1. [How to bind an event?](https://github.com/knsv/mermaid/issues/372) +1. [How to add newline in the text?](https://github.com/knsv/mermaid/issues/384#issuecomment-281339381) +1. [How to have special characters in link text?](https://github.com/knsv/mermaid/issues/407#issuecomment-329944735) +1. [How to change flowchart curve style?](https://github.com/knsv/mermaid/issues/580#issuecomment-373929046) diff --git a/docs/flowchart.md b/docs/flowchart.md new file mode 100644 index 000000000..00da49ff5 --- /dev/null +++ b/docs/flowchart.md @@ -0,0 +1,368 @@ +# Flowcharts - Basic Syntax + +## Graph + +This statement declares a new graph and the direction of the graph layout. + +This declares a graph oriented from top to bottom. + +```mermaid +graph TD + Start --> Stop +``` + +This declares a graph oriented from left to right. + +Possible directions are: + +* TB - top bottom +* BT - bottom top +* RL - right left +* LR - left right + +* TD - same as TB + +```mermaid +graph LR + Start --> Stop +``` + +## Nodes & shapes + +### A node (default) + +```mermaid +graph LR + id +``` +Note that the id is what is displayed in the box. + +### A node with text + +It is also possible to set text in the box that differs from the id. If this is done several times, it is the last text +found for the node that will be used. Also if you define edges for the node later on, you can omit text definitions. The +one previously defined will be used when rendering the box. + +```mermaid +graph LR + id1[This is the text in the box] +``` + + +### A node with round edges + +```mermaid +graph LR + id1(This is the text in the box) +``` + +### A node in the form of a circle + +```mermaid +graph LR + id1((This is the text in the circle)) +``` + +### A node in an asymetric shape + +```mermaid +graph LR + id1>This is the text in the box] +``` +Currently only the shape above is possible and not its mirror. *This might change with future releases.* + +### A node (rhombus) + +```mermaid +graph LR + id1{This is the text in the box} +``` + +## Links between nodes + +Nodes can be connected with links/edges. It is possible to have different types of links or attach a text string to a link. + +### A link with arrow head + +```mermaid +graph LR + A-->B +``` + +### An open link + +```mermaid +graph LR + A --- B +``` + +### Text on links + +```mermaid +graph LR + A-- This is the text ---B +``` + +or + +```mermaid +graph LR + A---|This is the text|B +``` + +### A link with arrow head and text + +```mermaid +graph LR + A-->|text|B +``` + +or + +```mermaid +graph LR + A-- text -->B +``` + +### Dotted link + +```mermaid +graph LR; + A-.->B; +``` + +### Dotted link with text + +```mermaid +graph LR + A-. text .-> B +``` + +### Thick link + +```mermaid +graph LR + A ==> B +``` + +### Thick link with text + +```mermaid +graph LR + A == text ==> B +``` + +## Special characters that break syntax + +It is possible to put text within quotes in order to render more troublesome characters. As in the example below: + +```mermaid +graph LR + id1["This is the (text) in the box"] +``` + +### Entity codes to escape characters + +It is possible to escape characters using the syntax examplified here. + +```mermaid + graph LR + A["A double quote:#quot;"] -->B["A dec char:#9829;"] +``` + +## Subgraphs + +``` +subgraph title + graph definition +end +``` + +An example below: + +```mermaid +graph TB + c1-->a2 + subgraph one + a1-->a2 + end + subgraph two + b1-->b2 + end + subgraph three + c1-->c2 + end + ``` + + +## Interaction + +It is possible to bind a click event to a node, the click can lead to either a javascript callback or to a link which will be opened in a new browser tab. + +``` +click nodeId callback +``` + +* nodeId is the id of the node +* callback is the name of a javascript function defined on the page displaying the graph, the function will be called with the nodeId as parameter. + +Examples of tooltip usage below: + +``` + + + + +
+ + + + + diff --git a/docs/mermaidAPI.md b/docs/mermaidAPI.md new file mode 100644 index 000000000..4f8595286 --- /dev/null +++ b/docs/mermaidAPI.md @@ -0,0 +1,103 @@ +# mermaidAPI + +> **Warning** This file is generated automatically from the comments of [mermaidAPI.js](https://github.com/knsv/mermaid/blob/master/src/mermaidAPI.js) file. Please read that file **instead** for up-to-date information. + +This is the api to be used when handling the integration with the web page instead of using the default integration (mermaid.js). + +The core of this api is the **render** function that given a graph definitionas text renders the graph/diagram and returns a svg element for the graph. It is is then up to the user of the API to make use of the svg, either insert it somewhere in the page or something completely different. + + +## Configuration + +These are the default options which can be overridden with the initialization call as in the example below: + +```javascript +mermaid.initialize({ + flowchart:{ + htmlLabels: false + } +}); +``` + + +## logLevel + +Decides the amount of logging to be used. + +- debug: 1 +- info: 2 +- warn: 3 +- error: 4 +- fatal: 5 + +**cloneCssStyles** - This options controls whether or not the css rules should be copied into the generated svg startOnLoad - This options controls whether or mermaid starts when the page loads +**arrowMarkerAbsolute** - This options controls whether or arrow markers in html code will be absolute paths or an anchor, #. This matters if you are using base tag settings. + + +## flowchart + +The object containing configurations specific for flowcharts +**htmlLabels** - Flag for setting whether or not a html tag should be used for rendering labels on the edges +**useMaxWidth** - Flag for setting whether or not a all available width should be used for the diagram. + + +## sequence + +The object containing configurations specific for sequence diagrams + +**diagramMarginX** - margin to the right and left of the sequence diagram +**diagramMarginY** - margin to the over and under the sequence diagram +**actorMargin** - Margin between actors +**width** - Width of actor boxes +**height** - Height of actor boxes +**boxMargin** - Margin around loop boxes +**boxTextMargin** - margin around the text in loop/alt/opt boxes +**noteMargin** - margin around notes +**messageMargin** - Space between messages +**mirrorActors** - mirror actors under diagram +**bottomMarginAdj** - Depending on css styling this might need adjustment. Prolongs the edge of the diagram downwards +**useMaxWidth** - when this flag is set the height and width is set to 100% and is then scaling with the available space if not the absolute space required is used + + +## gantt + +The object containing configurations specific for gantt diagrams + +**titleTopMargin** - margin top for the text over the gantt diagram +**barHeight** - the height of the bars in the graph +**barGap** - the margin between the different activities in the gantt diagram +**topPadding** - margin between title and gantt diagram and between axis and gantt diagram. +**leftPadding** - the space allocated for the section name to the left of the activities. +**gridLineStartPadding** - Vertical starting position of the grid lines +**fontSize** - font size ... +**fontFamily** - font family ... +**numberSectionStyles** - the number of alternating section styles +**axisFormatter** - formatting of the axis, this might need adjustment to match your locale and preferences + + +## parse + +Function that parses a mermaid diagram definition. If parsing fails the parseError callback is called and an error is thrown. + + +## version + +Function returning version information + + +## render + +Function that renders a svg with a graph from a chart definition. Usage example below: + +```javascript +mermaidAPI.initialize({ + startOnLoad: true +}) +$(function() { + var graphDefinition = 'graph TB\na-->b' + var cb = function(svgGraph) { + console.log(svgGraph) + } + mermaidAPI.render('id1',graphDefinition,cb) +}) +``` diff --git a/docs/mermaidCLI.md b/docs/mermaidCLI.md new file mode 100644 index 000000000..a7121dc96 --- /dev/null +++ b/docs/mermaidCLI.md @@ -0,0 +1,3 @@ +# mermaid CLI + +mermaid CLI has been moved to [mermaid.cli](https://github.com/mermaidjs/mermaid.cli). Please read its documentation instead. diff --git a/docs/sequenceDiagram.md b/docs/sequenceDiagram.md new file mode 100755 index 000000000..0468ac8d1 --- /dev/null +++ b/docs/sequenceDiagram.md @@ -0,0 +1,304 @@ +# Sequence diagrams + +> A Sequence diagram is an interaction diagram that shows how processes operate with one another and in what order. + +Mermaid can render sequence diagrams. + +```mermaid +sequenceDiagram + Alice->>John: Hello John, how are you? + John-->>Alice: Great! +``` + +## Syntax + +### Participants + +The participants can be defined implicitly as in the first example on this page. The participants or actors are +rendered in order of appearance in the diagram source text. Sometimes you might want to show the participants in a +different order than how they appear in the first message. It is possible to specify the actor's order of +appearance by doing the following: + +```mermaid +sequenceDiagram + participant John + participant Alice + Alice->>John: Hello John, how are you? + John-->>Alice: Great! +``` + +### Aliases + +The actor can have a convenient identifier and a descriptive label. + +```mermaid +sequenceDiagram + participant A as Alice + participant J as John + A->>J: Hello John, how are you? + J->>A: Great! +``` + +## Messages + +Messages can be of two displayed either solid or with a dotted line. + +``` +[Actor][Arrow][Actor]:Message text +``` + +There are six types of arrows currently supported: + +Type | Description +--- | --- +-> | Solid line without arrow +--> | Dotted line without arrow +->> | Solid line with arrowhead +-->> | Dotted line with arrowhead +-x | Solid line with a cross at the end (async) +--x | Dotted line with a cross at the end (async) + + +## Activations + +It is possible to activate and deactivate an actor. (de)activation can be dedicated declarations: + +```mermaid +sequenceDiagram + Alice->>John: Hello John, how are you? + activate John + John-->>Alice: Great! + deactivate John +``` + +There is also a shortcut notation by appending `+`/`-` suffix to the message arrow: + +```mermaid +sequenceDiagram + Alice->>+John: Hello John, how are you? + John-->>-Alice: Great! +``` + +Activations can be stacked for same actor: + +```mermaid +sequenceDiagram + Alice->>+John: Hello John, how are you? + Alice->>+John: John, can you hear me? + John-->>-Alice: Hi Alice, I can hear you! + John-->>-Alice: I feel great! +``` + + +## Notes + +It is possible to add notes to a sequence diagram. This is done by the notation +Note [ right of | left of | over ] [Actor]: Text in note content + +See the example below: + +```mermaid +sequenceDiagram + participant John + Note right of John: Text in note +``` + +It is also possible to create notes spanning two participants: + +```mermaid +sequenceDiagram + Alice->John: Hello John, how are you? + Note over Alice,John: A typical interaction +``` + + +## Loops + +It is possible to express loops in a sequence diagram. This is done by the notation + +``` +loop Loop text +... statements ... +end +``` + +See the example below: + +```mermaid +sequenceDiagram + Alice->John: Hello John, how are you? + loop Every minute + John-->Alice: Great! + end +``` + + +## Alt + +It is possible to express alternative paths in a sequence diagram. This is done by the notation + +``` +alt Describing text +... statements ... +else +... statements ... +end +``` + +or if there is sequence that is optional (if without else). + +``` +opt Describing text +... statements ... +end +``` + +See the example below: + +```mermaid +sequenceDiagram + Alice->>Bob: Hello Bob, how are you? + alt is sick + Bob->>Alice: Not so good :( + else is well + Bob->>Alice: Feeling fresh like a daisy + end + opt Extra response + Bob->>Alice: Thanks for asking + end +``` + + +## Styling + +Styling of the a sequence diagram is done by defining a number of css classes. During rendering these classes are extracted from the + +### Classes used + +Class | Description +--- | --- +actor | Style for the actor box at the top of the diagram. +text.actor | Styles for text in the actor box at the top of the diagram. +actor-line | The vertical line for an actor. +messageLine0 | Styles for the solid message line. +messageLine1 | Styles for the dotted message line. +messageText | Defines styles for the text on the message arrows. +labelBox | Defines styles label to left in a loop. +labelText | Styles for the text in label for loops. +loopText | Styles for the text in the loop box. +loopLine | Defines styles for the lines in the loop box. +note | Styles for the note box. +noteText | Styles for the text on in the note boxes. + + +### Sample stylesheet + + +```css +body { + background: white; +} + +.actor { + stroke: #CCCCFF; + fill: #ECECFF; +} +text.actor { + fill:black; + stroke:none; + font-family: Helvetica; +} + +.actor-line { + stroke:grey; +} + +.messageLine0 { + stroke-width:1.5; + stroke-dasharray: "2 2"; + marker-end:"url(#arrowhead)"; + stroke:black; +} + +.messageLine1 { + stroke-width:1.5; + stroke-dasharray: "2 2"; + stroke:black; +} + +#arrowhead { + fill:black; + +} + +.messageText { + fill:black; + stroke:none; + font-family: 'trebuchet ms', verdana, arial; + font-size:14px; +} + +.labelBox { + stroke: #CCCCFF; + fill: #ECECFF; +} + +.labelText { + fill:black; + stroke:none; + font-family: 'trebuchet ms', verdana, arial; +} + +.loopText { + fill:black; + stroke:none; + font-family: 'trebuchet ms', verdana, arial; +} + +.loopLine { + stroke-width:2; + stroke-dasharray: "2 2"; + marker-end:"url(#arrowhead)"; + stroke: #CCCCFF; +} + +.note { + stroke: #decc93; + stroke: #CCCCFF; + fill: #fff5ad; +} + +.noteText { + fill:black; + stroke:none; + font-family: 'trebuchet ms', verdana, arial; + font-size:14px; +} +``` + + +## Configuration + +Is it possible to adjust the margins for rendering the sequence diagram. + +This is done by defining `mermaid.sequenceConfig` or by the CLI to use a json file with the configuration. +How to use the CLI is described in the [mermaidCLI](mermaidCLI.html) page. +`mermaid.sequenceConfig` can be set to a JSON string with config parameters or the corresponding object. + +```javascript +mermaid.sequenceConfig = { + diagramMarginX:50, + diagramMarginY:10, + boxTextMargin:5, + noteMargin:10, + messageMargin:35, + mirrorActors:true +}; +``` + +### Possible configuration params: + +Param | Description | Default value +--- | --- | --- +mirrorActor | Turns on/off the rendering of actors below the diagram as well as above it | false +bottomMarginAdj | Adjusts how far down the graph ended. Wide borders styles with css could generate unwantewd clipping which is why this config param exists. | 1 diff --git a/docs/upgrading.md b/docs/upgrading.md new file mode 100644 index 000000000..9f318b3c7 --- /dev/null +++ b/docs/upgrading.md @@ -0,0 +1,28 @@ +# Upgrading + +Some of the interfaces has been upgraded. + + +## From version 0.4.0 to 0.5.0 + + +### Initialization + +`mermaid_config` is no longer used. Instead a call to mermaid initialize is done as in the example below: + + +#### version 0.4.0 + +```javascript +mermaid_config = { + startOnLoad: true +} +``` + +#### version 0.5.0 + +```javascript +mermaid.initialize({ + startOnLoad: true +}) +``` diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 000000000..544b2f89c --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,342 @@ +# Usage + +## Installation + +### npm package + +``` +yarn add mermaid +``` + +### CDN + +https://unpkg.com/mermaid/ + +Please note that you can switch versions through the dropdown box on top right. + + +## Simple usage on a web page + +The easiest way to integrate mermaid on a web page requires two elements: +1. Inclusion of the mermaid framework in the html page using a script tag +2. A graph definition on the web page + +If these things are in place mermaid listens to the page load event and when fires, when the page has loaded, it will +locate the graphs n 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 which will be replaced with the svg chart. + + +### Define a chart like this: + +```html +
+ CHART DEFINITION GOES HERE +
+``` + +Would end up like this: + +```html +
+ + Chart ends up here + +
+``` + +An id is also added to mermaid tags without id. + +### Simple full example: + +```html + + + + + + + +
+ graph LR + A --- B + B-->C[fa:fa-ban forbidden] + B-->D(fa:fa-spinner); +
+ + + + +``` + +### Labels out of bounds + +If you use dynamically loaded fonts that are loaded through CSS, such as Google fonts, mermaid should wait for the +whole page to have been loaded (dom + assets, particularly the fonts file). + +```javascript +$(document).load(function() { + mermaid.initialize(); +}); +``` + +or + +```javascript +$(document).ready(function() { + mermaid.initialize(); +}); +``` + +Not doing so will most likely result in mermaid rendering graphs that have labels out of bounds. The default integration +in mermaid uses the window.load event to start rendering. + +### Calling `mermaid.init` + +By default, `mermaid.init` will be called when the document is ready, finding all elements with +`class="mermaid"`. If you are adding content after mermaid is loaded, or otherwise need +finer-grained control of this behavior, you can call `init` yourself with: + +- a configuration object +- some nodes, as + - a node + - an a array-like of nodes + - or W3C selector that will find your nodes + +Example: + +```javascript +mermaid.init({noteMargin: 10}, ".someOtherClass"); +``` + +Or with no config object, and a jQuery selection: + +```javascript +mermaid.init(undefined, $("#someId .yetAnotherClass")); +``` + +> **Warning** This type of integration is deprecated instead the preferred way of handling more complex integration is to us the mermaidAPI instead. + + +## Usage with webpack + +mermaid fully supports webpack. Here is a [working demo](https://github.com/mermaidjs/mermaid-webpack-demo). + + +## API usage + +The main idea with the API is to be able to call a render function with graph defintion as a string. The render function +will render the graph and call a callback with the resulting svg code. With this approach it is up to the site creator to +fetch the graph definition from the site, perhaps from a textarea, render it and place the graph somewhere in the site. + +To do this, include mermaidAPI on your web website instead of mermaid.js. The example below show an outline of how this +could be used. The example just logs the resulting svg to the javascript console. + +```html + + + +``` + + +### Binding events + +Sometimes the generated graph also has defined interactions like tooltip and click events. When using the API one must +add those events after the graph has been inserted into the DOM. + +The example code below is an extract of what mermaid does when using the API. The example shows how it is possible to +bind events to an svg when using the API for rendering. + +```javascript +var insertSvg = function(svgCode, bindFunctions) { + element.innerHTML = svgCode; + if(typeof callback !== 'undefined'){ + callback(id); + } + bindFunctions(element); +}; + +var id = 'theGraph'; + + +mermaidAPI.render(id,txt,insertSvg, element); +``` + +1. The graph is generated using the render call. +2. After generation the render function calls the provided callback function, in this case it's called insertSvg. +3. The callback function is called with two parameters, the svg code of the generated graph and a function. This function binds events to the svg **after** it is inserted into the DOM. +4. Insert the svg code into the DOM for presentation +5. Call the binding function that binds the events + + +## Example of a marked renderer + +This is the renderer used for transforming the documentation from markdown to html with mermaid diagrams in the html. + +```javascript +var renderer = new marked.Renderer(); +renderer.code = function (code, language) { + if(code.match(/^sequenceDiagram/)||code.match(/^graph/)){ + return '
'+code+'
'; + } + else{ + return '
'+code+'
'; + } +}; +``` + +Another example in coffeescript that also includes the mermaid script tag into the generated markup. + +```CoffeeScript +marked = require 'marked' + +module.exports = (options) -> + hasMermaid = false + renderer = new marked.Renderer() + renderer.defaultCode = renderer.code + renderer.code = (code, language) -> + if language is 'mermaid' + html = '' + if not hasMermaid + hasMermaid = true + html += '' + html + '
'+code+'
' + else + @defaultCode(code, language) + + renderer +``` + + +## Advanced usage + +**Error handling** + +When the parser encounters invalid syntax the **mermaid.parseError** function is called. It is possible to override this +function in order to handle the error in an application specific way. + +**Parsing text without rendering** + +It is also possible to validate the syntax before rendering in order to streamline the user experience. The function +**mermaid.parse(txt)** takes a text string as an argument and returns true if the text is syntactically correct and +false if it is not. The parseError function will be called when the parse function returns false. + +The code-example below in meta code illustrates how this could work: + +```javascript +mermaid.parseError = function(err,hash){ + displayErrorInGui(err); +}; + +var textFieldUpdated = function(){ + var textStr = getTextFromFormField('code'); + + if(mermaid.parse(textStr)){ + reRender(textStr) + } +}; + +bindEventHandler('change', 'code', textFieldUpdated); +``` + + +## Configuration + +Mermaid takes a number of options which lets you tweak the rendering of the diagrams. Currently there are three ways of +setting the options in mermaid. + +1. Instantiation of the configuration using the initialize call +2. *Using the global mermaid object* - deprecated +3. *using the global mermaid_config object* - deprecated +4. Instantiation of the configuration using the **mermaid.init** call + +The list above has two ways to many of doing this. Three are deprecated and will eventually be removed. The list of +configuration objects are described [in the mermaidAPI documentation](mermaidAPI.html). + + +## Using the `mermaidAPI.initialize`/`mermaid.initialize` call + +The future proof way of setting the configuration is by using the initialization call to mermaid or mermaidAPi depending +on what kind of integration you use. + +```html + + +``` + +> **Success** This is the preferred way of configuring mermaid. + + +## Using the mermaid object + +Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this +approach are: + +* mermaid.startOnLoad +* mermaid.htmlLabels + +``` +mermaid.startOnLoad = true; +``` + +> **Warning** This way of setting the configuration is deprecated instead the preferred way of is to use the initialize method. This functionality is only kept for not breaking existing integrations + +## Using the mermaid_config + +Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this +approach are: + +* mermaid_config.startOnLoad +* mermaid_config.htmlLabels + +```javascript +mermaid_config.startOnLoad = true; +``` + +> **Warning** This way of setting the configuration is deprecated instead the preferred way of is to use the initialize method. This functionality is only kept for not breaking existing integrations + +## Using the mermaid.init call + +Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this +approach are: + +* mermaid_config.startOnLoad +* mermaid_config.htmlLabels + +``` +mermaid_config.startOnLoad = true; +``` + +> **Warning** This way of setting the configuration is deprecated instead the preferred way of is to use the initialize method. This functionality is only kept for not breaking existing integrations