index.md · grove

19.2 KB476 lines

1	> Warning
2	>
3	> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
4	>
5	> ## Please edit the corresponding file in [/packages/mermaid/src/docs/intro/index.md](../../packages/mermaid/src/docs/intro/index.md).
6
7	# About Mermaid
8
9	Mermaid lets you create diagrams and visualizations using text and code.
10
11	It is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.
12
13	> If you are familiar with Markdown you should have no problem learning [Mermaid's Syntax](syntax-reference.md).
14
15	<img src="/header.png" alt="" />
16
17	<div class='badges'>
18
19	[![Build CI Status](https://github.com/mermaid-js/mermaid/actions/workflows/build.yml/badge.svg)](https://github.com/mermaid-js/mermaid/actions/workflows/build.yml)
20	[![NPM](https://img.shields.io/npm/v/mermaid)](https://www.npmjs.com/package/mermaid)
21	[![npm minified gzipped bundle size](https://img.shields.io/bundlephobia/minzip/mermaid)](https://bundlephobia.com/package/mermaid)
22	[![Coverage Status](https://coveralls.io/repos/github/mermaid-js/mermaid/badge.svg?branch=master)](https://coveralls.io/github/mermaid-js/mermaid?branch=master)
23	[![CDN Status](https://img.shields.io/jsdelivr/npm/hm/mermaid)](https://www.jsdelivr.com/package/npm/mermaid)
24	[![NPM](https://img.shields.io/npm/dm/mermaid)](https://www.npmjs.com/package/mermaid)
25	[![Join our Discord!](https://img.shields.io/static/v1?message=join%20chat&color=9cf&logo=discord&label=discord)](https://discord.gg/sKeNQX4Wtj)
26	[![Twitter Follow](https://img.shields.io/twitter/follow/mermaidjs_?style=social)](https://twitter.com/mermaidjs_)
27
28	</div>
29
30	<!-- Mermaid book banner -->
31
32	[![Explore Mermaid.js in depth, with real-world examples, tips & tricks from the creator... The first official book on Mermaid is available for purchase. Check it out!](img/book-banner-post-release.jpg)](https://mermaid-js.github.io/mermaid/landing/)
33
34	<!-- <Main description> -->
35
36	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.
37
38	> Doc-Rot is a Catch-22 that Mermaid helps to solve.
39
40	Diagramming and documentation costs precious developer time and gets outdated quickly.
41	But not having diagrams or docs ruins productivity and hurts organizational learning.<br/>
42	Mermaid addresses this problem by enabling users to create easily modifiable diagrams, it can also be made part of production scripts (and other pieces of code).<br/> <br/>
43	Mermaid allows even non-programmers to easily create detailed and diagrams through the [Mermaid Live Editor](https://mermaid.live/).<br/>
44	[Tutorials](../ecosystem/tutorials.md) has video tutorials.
45
46	Use Mermaid with your favorite applications, check out the list of [Community Integrations](../ecosystem/integrations-community.md).
47
48	For a more detailed introduction to Mermaid and some of its more basic uses, look to the [Beginner's Guide](../intro/getting-started.md) and [Usage](../config/usage.md).
49
50	🌐 [CDN](https://www.jsdelivr.com/package/npm/mermaid) \| 📖 [Documentation](https://mermaidjs.github.io) \| 🙌 [Contribution](../community/contributing.md) \| 🔌 [Plug-Ins](../ecosystem/integrations-community.md)
51
52	> 🖖 Keep a steady pulse: [mermaid needs more Collaborators](https://github.com/mermaid-js/mermaid/issues/866).
53
54	: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"!!!
55
56	Thanks to all involved, people committing pull requests, people answering questions and special thanks to Tyler Long who is helping me maintain the project 🙏
57
58	Our PR Visual Regression Testing is powered by [Argos](https://argos-ci.com/?utm_source=mermaid&utm_campaign=oss) with their generous Open Source plan. It makes the process of reviewing PRs with visual changes a breeze.
59
60	[![Covered by Argos Visual Testing](https://argos-ci.com/badge-large.svg)](https://argos-ci.com?utm_source=mermaid&utm_campaign=oss)
61
62	In our release process we rely heavily on visual regression tests using [applitools](https://applitools.com/). Applitools is a great service which has been easy to use and integrate with our tests.
63
64	<a href="https://applitools.com/">
65	<svg width="170" height="32" viewBox="0 0 170 32" fill="none" xmlns="http://www.w3.org/2000/svg"><mask id="a" maskUnits="userSpaceOnUse" x="27" y="0" width="143" height="32"><path fill-rule="evenodd" clip-rule="evenodd" d="M27.732.227h141.391v31.19H27.733V.227z" fill="#fff"></path></mask><g mask="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M153.851 22.562l1.971-3.298c1.291 1.219 3.837 2.402 5.988 2.402 1.971 0 2.903-.753 2.903-1.829 0-2.832-10.253-.502-10.253-7.313 0-2.904 2.51-5.45 7.099-5.45 2.904 0 5.234 1.004 6.955 2.367l-1.829 3.226c-1.039-1.075-3.011-2.008-5.126-2.008-1.65 0-2.725.717-2.725 1.685 0 2.546 10.289.395 10.289 7.386 0 3.19-2.724 5.52-7.528 5.52-3.012 0-5.916-1.003-7.744-2.688zm-5.7 2.259h4.553V.908h-4.553v23.913zm-6.273-8.676c0-2.689-1.578-5.02-4.446-5.02-2.832 0-4.409 2.331-4.409 5.02 0 2.724 1.577 5.055 4.409 5.055 2.868 0 4.446-2.33 4.446-5.055zm-13.588 0c0-4.912 3.442-9.07 9.142-9.07 5.736 0 9.178 4.158 9.178 9.07 0 4.911-3.442 9.106-9.178 9.106-5.7 0-9.142-4.195-9.142-9.106zm-5.628 0c0-2.689-1.577-5.02-4.445-5.02-2.832 0-4.41 2.331-4.41 5.02 0 2.724 1.578 5.055 4.41 5.055 2.868 0 4.445-2.33 4.445-5.055zm-13.587 0c0-4.912 3.441-9.07 9.142-9.07 5.736 0 9.178 4.158 9.178 9.07 0 4.911-3.442 9.106-9.178 9.106-5.701 0-9.142-4.195-9.142-9.106zm-8.425 4.338v-8.999h-2.868v-3.98h2.868V2.773h4.553v4.733h3.514v3.979h-3.514v7.78c0 1.111.574 1.936 1.578 1.936.681 0 1.326-.251 1.577-.538l.968 3.478c-.681.609-1.9 1.11-3.8 1.11-3.191 0-4.876-1.648-4.876-4.767zm-8.962 4.338h4.553V7.505h-4.553V24.82zm-.43-21.905a2.685 2.685 0 012.688-2.69c1.506 0 2.725 1.184 2.725 2.69a2.724 2.724 0 01-2.725 2.724c-1.47 0-2.688-1.219-2.688-2.724zM84.482 24.82h4.553V.908h-4.553v23.913zm-6.165-8.676c0-2.976-1.793-5.02-4.41-5.02-1.47 0-3.119.825-3.908 1.973v6.094c.753 1.111 2.438 2.008 3.908 2.008 2.617 0 4.41-2.044 4.41-5.055zm-8.318 6.453v8.82h-4.553V7.504H70v2.187c1.327-1.685 3.227-2.618 5.342-2.618 4.446 0 7.672 3.299 7.672 9.07 0 5.773-3.226 9.107-7.672 9.107-2.043 0-3.907-.86-5.342-2.653zm-10.718-6.453c0-2.976-1.793-5.02-4.41-5.02-1.47 0-3.119.825-3.908 1.973v6.094c.753 1.111 2.438 2.008 3.908 2.008 2.617 0 4.41-2.044 4.41-5.055zm-8.318 6.453v8.82H46.41V7.504h4.553v2.187c1.327-1.685 3.227-2.618 5.342-2.618 4.446 0 7.672 3.299 7.672 9.07 0 5.773-3.226 9.107-7.672 9.107-2.043 0-3.908-.86-5.342-2.653zm-11.758-1.936V18.51c-.753-1.004-2.187-1.542-3.657-1.542-1.793 0-3.263.968-3.263 2.617 0 1.65 1.47 2.582 3.263 2.582 1.47 0 2.904-.502 3.657-1.506zm0 4.159v-1.829c-1.183 1.434-3.227 2.259-5.485 2.259-2.761 0-5.988-1.864-5.988-5.736 0-4.087 3.227-5.593 5.988-5.593 2.33 0 4.337.753 5.485 2.115V13.85c0-1.756-1.506-2.904-3.8-2.904-1.829 0-3.55.717-4.984 2.044L28.63 9.8c2.115-1.901 4.84-2.726 7.564-2.726 3.98 0 7.6 1.578 7.6 6.561v11.186h-4.588z" fill="#00A298"></path></g><path fill-rule="evenodd" clip-rule="evenodd" d="M14.934 16.177c0 1.287-.136 2.541-.391 3.752-1.666-1.039-3.87-2.288-6.777-3.752 2.907-1.465 5.11-2.714 6.777-3.753.255 1.211.39 2.466.39 3.753m4.6-7.666V4.486a78.064 78.064 0 01-4.336 3.567c-1.551-2.367-3.533-4.038-6.14-5.207C11.1 4.658 12.504 6.7 13.564 9.262 5.35 15.155 0 16.177 0 16.177s5.35 1.021 13.564 6.915c-1.06 2.563-2.463 4.603-4.507 6.415 2.607-1.169 4.589-2.84 6.14-5.207a77.978 77.978 0 014.336 3.568v-4.025s-.492-.82-2.846-2.492c.6-1.611.93-3.354.93-5.174a14.8 14.8 0 00-.93-5.174c2.354-1.673 2.846-2.492 2.846-2.492" fill="#00A298"></path></svg>
66	</a>
67
68	## Diagram Types
69
70	### [Flowchart](../syntax/flowchart.md?id=flowcharts-basic-syntax)
71
72	```mermaid-example
73	graph TD;
74	A-->B;
75	A-->C;
76	B-->D;
77	C-->D;
78	```
79
80	```mermaid
81	graph TD;
82	A-->B;
83	A-->C;
84	B-->D;
85	C-->D;
86	```
87
88	### [Sequence diagram](../syntax/sequenceDiagram.md)
89
90	```mermaid-example
91	sequenceDiagram
92	participant Alice
93	participant Bob
94	Alice->>John: Hello John, how are you?
95	loop HealthCheck
96	John->>John: Fight against hypochondria
97	end
98	Note right of John: Rational thoughts <br/>prevail!
99	John-->>Alice: Great!
100	John->>Bob: How about you?
101	Bob-->>John: Jolly good!
102	```
103
104	```mermaid
105	sequenceDiagram
106	participant Alice
107	participant Bob
108	Alice->>John: Hello John, how are you?
109	loop HealthCheck
110	John->>John: Fight against hypochondria
111	end
112	Note right of John: Rational thoughts <br/>prevail!
113	John-->>Alice: Great!
114	John->>Bob: How about you?
115	Bob-->>John: Jolly good!
116	```
117
118	### [Gantt diagram](../syntax/gantt.md)
119
120	```mermaid-example
121	gantt
122	dateFormat YYYY-MM-DD
123	title Adding GANTT diagram to mermaid
124	excludes weekdays 2014-01-10
125
126	section A section
127	Completed task :done, des1, 2014-01-06,2014-01-08
128	Active task :active, des2, 2014-01-09, 3d
129	Future task : des3, after des2, 5d
130	Future task2 : des4, after des3, 5d
131	```
132
133	```mermaid
134	gantt
135	dateFormat YYYY-MM-DD
136	title Adding GANTT diagram to mermaid
137	excludes weekdays 2014-01-10
138
139	section A section
140	Completed task :done, des1, 2014-01-06,2014-01-08
141	Active task :active, des2, 2014-01-09, 3d
142	Future task : des3, after des2, 5d
143	Future task2 : des4, after des3, 5d
144	```
145
146	### [Class diagram](../syntax/classDiagram.md)
147
148	```mermaid-example
149	classDiagram
150	Class01 <\|-- AveryLongClass : Cool
151	Class03 *-- Class04
152	Class05 o-- Class06
153	Class07 .. Class08
154	Class09 --> C2 : Where am i?
155	Class09 --* C3
156	Class09 --\|> Class07
157	Class07 : equals()
158	Class07 : Object[] elementData
159	Class01 : size()
160	Class01 : int chimp
161	Class01 : int gorilla
162	Class08 <--> C2: Cool label
163	```
164
165	```mermaid
166	classDiagram
167	Class01 <\|-- AveryLongClass : Cool
168	Class03 *-- Class04
169	Class05 o-- Class06
170	Class07 .. Class08
171	Class09 --> C2 : Where am i?
172	Class09 --* C3
173	Class09 --\|> Class07
174	Class07 : equals()
175	Class07 : Object[] elementData
176	Class01 : size()
177	Class01 : int chimp
178	Class01 : int gorilla
179	Class08 <--> C2: Cool label
180	```
181
182	### [Git graph](../syntax/gitgraph.md)
183
184	```mermaid-example
185	gitGraph
186	commit
187	commit
188	branch develop
189	commit
190	commit
191	commit
192	checkout main
193	commit
194	commit
195	```
196
197	```mermaid
198	gitGraph
199	commit
200	commit
201	branch develop
202	commit
203	commit
204	commit
205	checkout main
206	commit
207	commit
208	```
209
210	### [Entity Relationship Diagram - :exclamation: experimental](../syntax/entityRelationshipDiagram.md)
211
212	```mermaid-example
213	erDiagram
214	CUSTOMER \|\|--o{ ORDER : places
215	ORDER \|\|--\|{ LINE-ITEM : contains
216	CUSTOMER }\|..\|{ DELIVERY-ADDRESS : uses
217
218	```
219
220	```mermaid
221	erDiagram
222	CUSTOMER \|\|--o{ ORDER : places
223	ORDER \|\|--\|{ LINE-ITEM : contains
224	CUSTOMER }\|..\|{ DELIVERY-ADDRESS : uses
225
226	```
227
228	### [User Journey Diagram](../syntax/userJourney.md)
229
230	```mermaid-example
231	journey
232	title My working day
233	section Go to work
234	Make tea: 5: Me
235	Go upstairs: 3: Me
236	Do work: 1: Me, Cat
237	section Go home
238	Go downstairs: 5: Me
239	Sit down: 5: Me
240	```
241
242	```mermaid
243	journey
244	title My working day
245	section Go to work
246	Make tea: 5: Me
247	Go upstairs: 3: Me
248	Do work: 1: Me, Cat
249	section Go home
250	Go downstairs: 5: Me
251	Sit down: 5: Me
252	```
253
254	### [Quadrant Chart](../syntax/quadrantChart.md)
255
256	```mermaid-example
257	quadrantChart
258	title Reach and engagement of campaigns
259	x-axis Low Reach --> High Reach
260	y-axis Low Engagement --> High Engagement
261	quadrant-1 We should expand
262	quadrant-2 Need to promote
263	quadrant-3 Re-evaluate
264	quadrant-4 May be improved
265	Campaign A: [0.3, 0.6]
266	Campaign B: [0.45, 0.23]
267	Campaign C: [0.57, 0.69]
268	Campaign D: [0.78, 0.34]
269	Campaign E: [0.40, 0.34]
270	Campaign F: [0.35, 0.78]
271	```
272
273	```mermaid
274	quadrantChart
275	title Reach and engagement of campaigns
276	x-axis Low Reach --> High Reach
277	y-axis Low Engagement --> High Engagement
278	quadrant-1 We should expand
279	quadrant-2 Need to promote
280	quadrant-3 Re-evaluate
281	quadrant-4 May be improved
282	Campaign A: [0.3, 0.6]
283	Campaign B: [0.45, 0.23]
284	Campaign C: [0.57, 0.69]
285	Campaign D: [0.78, 0.34]
286	Campaign E: [0.40, 0.34]
287	Campaign F: [0.35, 0.78]
288	```
289
290	### [XY Chart](../syntax/xyChart.md)
291
292	```mermaid-example
293	xychart-beta
294	title "Sales Revenue"
295	x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
296	y-axis "Revenue (in $)" 4000 --> 11000
297	bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
298	line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
299	```
300
301	```mermaid
302	xychart-beta
303	title "Sales Revenue"
304	x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
305	y-axis "Revenue (in $)" 4000 --> 11000
306	bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
307	line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
308	```
309
310	## Installation
311
312	In depth guides and examples can be found at [Getting Started](./getting-started.md) and [Usage](../config/usage.md).
313
314	It would also be helpful to learn more about mermaid's [Syntax](./syntax-reference.md).
315
316	### CDN
317
318	```
319	https://cdn.jsdelivr.net/npm/mermaid@<version>/dist/
320	```
321
322	To select a version:
323
324	Replace `<version>` with the desired version number.
325
326	Latest Version: <https://cdn.jsdelivr.net/npm/mermaid@11>
327
328	## Deploying Mermaid
329
330	To Deploy Mermaid:
331
332	1. You will need to install node v16, which would have npm
333	2. Install mermaid
334	- NPM: `npm i mermaid`
335	- Yarn: `yarn add mermaid`
336	- Pnpm: `pnpm add mermaid`
337
338	### [Mermaid API](../config/setup/README.md):
339
340	To deploy mermaid without a bundler, insert a `script` tag with an absolute address and a `mermaid.initialize` call into the HTML using the following example:
341
342	```html
343	<script type="module">
344	import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
345	mermaid.initialize({ startOnLoad: true });
346	</script>
347	```
348
349	Doing so commands the mermaid parser to look for the `<div>` or `<pre>` tags with `class="mermaid"`. From these tags, mermaid tries to read the diagram/chart definitions and render them into SVG charts.
350
351	Examples can be found in [Other examples](../syntax/examples.md)
352
353	## Sibling projects
354
355	- [Mermaid Live Editor](https://github.com/mermaid-js/mermaid-live-editor)
356	- [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli)
357	- [Mermaid Tiny](https://github.com/mermaid-js/mermaid/tree/develop/packages/tiny)
358	- [Mermaid Webpack Demo](https://github.com/mermaidjs/mermaid-webpack-demo)
359	- [Mermaid Parcel Demo](https://github.com/mermaidjs/mermaid-parcel-demo)
360
361	## Request for Assistance
362
363	Things are piling up and I have a hard time keeping up. It would be great if we could form a core team of developers to cooperate
364	with the future development of mermaid.
365
366	As part of this team you would get write access to the repository and would
367	represent the project when answering questions and issues.
368
369	Together we could continue the work with things like:
370
371	- Adding more types of diagrams like mindmaps, ert diagrams, etc.
372	- Improving existing diagrams
373
374	Don't hesitate to contact me if you want to get involved!
375
376	## Contributors
377
378	<div class='badges'>
379
380	[![Good first issue](https://img.shields.io/github/labels/mermaid-js/mermaid/Good%20first%20issue%21)](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Good+first+issue%21%22)
381	[![Contributors](https://img.shields.io/github/contributors/mermaid-js/mermaid)](https://github.com/mermaid-js/mermaid/graphs/contributors)
382	[![Commits](https://img.shields.io/github/commit-activity/m/mermaid-js/mermaid)](https://github.com/mermaid-js/mermaid/graphs/contributors)
383
384	</div>
385
386	Mermaid is a growing community and is always accepting new contributors. There's a lot of different ways to help out and we're always looking for extra hands! Look at [this issue](https://github.com/mermaid-js/mermaid/issues/866) if you want to know where to start helping out.
387
388	Detailed information about how to contribute can be found in the [contribution guideline](../community/contributing.md).
389
390	### Requirements
391
392	- [volta](https://volta.sh/) to manage node versions.
393	- [Node.js](https://nodejs.org/en/). `volta install node`
394	- [pnpm](https://pnpm.io/) package manager. `volta install pnpm`
395
396	### Development Installation
397
398	```bash
399	git clone git@github.com:mermaid-js/mermaid.git
400	cd mermaid
401	# npx is required for first install as volta support for pnpm is not added yet.
402	npx pnpm install
403	pnpm test
404	```
405
406	### Lint
407
408	```sh
409	pnpm lint
410	```
411
412	We use [eslint](https://eslint.org/).
413	We recommend you to install [editor plugins](https://eslint.org/docs/user-guide/integrations) to get real time lint result.
414
415	### Test
416
417	```sh
418	pnpm test
419	```
420
421	Manual test in browser: open `dist/index.html`
422
423	### Release
424
425	For those who have the permission to do so:
426
427	Update version number in `package.json`.
428
429	```sh
430	npm publish
431	```
432
433	The above command generates files into the `dist` folder and publishes them to [npmjs.com](https://www.npmjs.com/).
434
435	## Security and safe diagrams
436
437	For public sites, it can be precarious to retrieve text from users on the internet, storing that content for presentation in a browser at a later stage. The reason is that the user content can contain embedded malicious scripts that will run when the data is presented. For Mermaid this is a risk, specially as mermaid diagrams contain many characters that are used in html which makes the standard sanitation unusable as it also breaks the diagrams. We still make an effort to sanitize the incoming code and keep refining the process but it is hard to guarantee that there are no loop holes.
438
439	As an extra level of security for sites with external users we are happy to introduce a new security level in which the diagram is rendered in a sandboxed iframe preventing JavaScript in the code from being executed. This is a great step forward for better security.
440
441	_Unfortunately you cannot have a cake and eat it at the same time which in this case means that some of the interactive functionality gets blocked along with the possible malicious code._
442
443	## Reporting vulnerabilities
444
445	To report a vulnerability, please e-mail <security@mermaid.live> with a description of the issue, the steps you took to create the issue, affected versions, and if known, mitigations for the issue.
446
447	## Appreciation
448
449	A quick note from Knut Sveidqvist:
450
451	> _Many thanks to the [d3](https://d3js.org/) and [dagre-d3](https://github.com/cpettitt/dagre-d3) projects for providing the graphical layout and drawing libraries!_
452	>
453	> _Thanks also to the [js-sequence-diagram](https://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._
454	>
455	> _Thank you to [Tyler Long](https://github.com/tylerlong) who has been a collaborator since April 2017._
456	>
457	> _Thank you to the ever-growing list of [contributors](https://github.com/mermaid-js/mermaid/graphs/contributors) that brought the project this far!_
458
459	---
460
461	_Mermaid was created by Knut Sveidqvist for easier documentation._
462
463	<style scoped>
464	.badges > p {
465	display: flex;
466	}
467
468	.badges > p > a {
469	margin: 0 0.5rem;
470	}
471
472	.dark #VPContent > div > div > div.content > div > main > div > div > img {
473	filter: invert(1) hue-rotate(217deg) contrast(0.72);
474	}
475	</style>
476