syntax-reference.md

10.8 KB263 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/syntax-reference.md](../../packages/mermaid/src/docs/intro/syntax-reference.md).
6
7	# Diagram Syntax
8
9	Mermaid's syntax is used to create diagrams. You'll find that it is not too tricky and can be learned in a day. The next sections dive deep into the syntax of each diagram type.
10
11	Syntax, together with Deployment and Configuration constitute the whole of Mermaid.
12
13	Diagram Examples can be found in the [Mermaid Live Editor](https://mermaid.live), it is also a great practice area.
14
15	## Syntax Structure
16
17	One would notice that all Diagrams definitions begin with a declaration of the diagram type, followed by the definitions of the diagram and its contents. This declaration notifies the parser which kind of diagram the code is supposed to generate. The only exception to this a [Frontmatter](#frontmatter-for-diagram-code) configuration.
18
19	Line comments can ignore anything on the line after '%% '.
20
21	Unknown words and misspellings will break a diagram, while parameters silently fail.
22
23	Example : The code below is for an Entity Relationship Diagram, specified by the `erDiagram` declaration. What follows is the definition of the different `Entities` represented in it.
24
25	```mermaid-example
26	erDiagram
27	CUSTOMER }\|..\|{ DELIVERY-ADDRESS : has
28	CUSTOMER \|\|--o{ ORDER : places
29	CUSTOMER \|\|--o{ INVOICE : "liable for"
30	DELIVERY-ADDRESS \|\|--o{ ORDER : receives
31	INVOICE \|\|--\|{ ORDER : covers
32	ORDER \|\|--\|{ ORDER-ITEM : includes
33	PRODUCT-CATEGORY \|\|--\|{ PRODUCT : contains
34	PRODUCT \|\|--o{ ORDER-ITEM : "ordered in"
35	```
36
37	```mermaid
38	erDiagram
39	CUSTOMER }\|..\|{ DELIVERY-ADDRESS : has
40	CUSTOMER \|\|--o{ ORDER : places
41	CUSTOMER \|\|--o{ INVOICE : "liable for"
42	DELIVERY-ADDRESS \|\|--o{ ORDER : receives
43	INVOICE \|\|--\|{ ORDER : covers
44	ORDER \|\|--\|{ ORDER-ITEM : includes
45	PRODUCT-CATEGORY \|\|--\|{ PRODUCT : contains
46	PRODUCT \|\|--o{ ORDER-ITEM : "ordered in"
47	```
48
49	The [Getting Started](./getting-started.md) section can also provide some practical examples of mermaid syntax.
50
51	## Diagram Breaking
52
53	One should beware the use of some words or symbols that can break diagrams. These words or symbols are few and often only affect specific types of diagrams. The table below will continuously be updated.
54
55	\| Diagram Breakers \| Reason \| Solution \|
56	\| ------------------------------------------------------------------------------------ \| ----------------------------------------------------------------------- \| ------------------------------------------------- \|
57	\| Comments \| \| \|
58	\| [`%%{``}%%`](https://github.com/mermaid-js/mermaid/issues/1968) \| Similar to [Directives](../config/directives.md) confuses the renderer. \| In comments using `%%`, avoid using "{}". \|
59	\| Flow-Charts \| \| \|
60	\| 'end' \| The word "End" can cause Flowcharts and Sequence diagrams to break \| Wrap them in quotation marks to prevent breakage. \|
61	\| [Nodes inside Nodes](../syntax/flowchart.md?id=special-characters-that-break-syntax) \| Mermaid gets confused with nested shapes \| wrap them in quotation marks to prevent breaking \|
62
63	## Mermaid Live Editor
64
65	Now, that you've seen what you should not add to your diagrams, you can play around with them in the [Mermaid Live Editor](https://mermaid.live).
66
67	## Configuration
68
69	Configuration is the third part of Mermaid, after deployment and syntax. It deals with the different ways that Mermaid can be customized across different deployments.
70
71	If you are interested in altering and customizing your Mermaid Diagrams, you will find the methods and values available for [Configuration](../config/setup/README.md) here. It includes themes.
72	This section will introduce the different methods of configuring the behaviors and appearances of Mermaid Diagrams.
73	The following are the most commonly used methods, and they are all tied to Mermaid [Deployment](./getting-started.md) methods.
74
75	### Configuration Section in the [Live Editor](https://mermaid.live).
76
77	Here you can edit certain values to change the behavior and appearance of the diagram.
78
79	Each of these techniques are functionally equivalent, but better for different deployments.
80
81	### [The initialize() call](./getting-started.md#_3-calling-the-javascript-api)
82
83	Used when Mermaid is called via an API, or through a `<script>` tag.
84
85	### Frontmatter for diagram code
86
87	Frontmatter is the term for adding YAML metadata at the start of code. This allows for reconfiguration of a diagram before it is rendered. You can pass metadata Frontmatter with your definition by adding `---` to the lines before and after the definition. This 'triple dash' MUST be the only character on the first line.
88
89	Frontmatter uses YAML syntax. It requires any indentation to be consistent and settings are case sensitive. Mermaid will silently ignore misspelling, but badly formed parameters will break the diagram.
90
91	```mermaid-example
92	---
93	title: Frontmatter Example
94	displayMode: compact
95	config:
96	theme: forest
97	gantt:
98	useWidth: 400
99	compact: true
100	---
101	gantt
102	section Waffle
103	Iron : 1982, 3y
104	House : 1986, 3y
105	```
106
107	```mermaid
108	---
109	title: Frontmatter Example
110	displayMode: compact
111	config:
112	theme: forest
113	gantt:
114	useWidth: 400
115	compact: true
116	---
117	gantt
118	section Waffle
119	Iron : 1982, 3y
120	House : 1986, 3y
121	```
122
123	### [Directives](../config/directives.md)
124
125	Allows for the limited reconfiguration of a diagram just before it is rendered. It can alter the font style, color and other aesthetic aspects of the diagram. You can pass a directive alongside your definition inside `%%{ }%%`. It can be done either above or below your diagram definition.
126
127	### [Theme Manipulation](../config/theming.md)
128
129	An application of using Directives to change [Themes](../config/theming.md). `Theme` is a value within Mermaid's configuration that dictates the color scheme for diagrams.
130
131	### Layout and look
132
133	We've restructured how Mermaid renders diagrams, enabling new features like selecting layout and look. Currently, this is supported for flowcharts and state diagrams, with plans to extend support to all diagram types.
134
135	### Selecting Diagram Looks
136
137	Mermaid offers a variety of styles or “looks” for your diagrams, allowing you to tailor the visual appearance to match your specific needs or preferences. Whether you prefer a hand-drawn or classic style, you can easily customize your diagrams.
138
139	Available Looks:
140
141	- Hand-Drawn Look: For a more personal, creative touch, the hand-drawn look brings a sketch-like quality to your diagrams. This style is perfect for informal settings or when you want to add a bit of personality to your diagrams.
142	- Classic Look: If you prefer the traditional Mermaid style, the classic look maintains the original appearance that many users are familiar with. It’s great for consistency across projects or when you want to keep the familiar aesthetic.
143
144	How to Select a Look:
145
146	You can select a look by adding the look parameter in the metadata section of your Mermaid diagram code. Here’s an example:
147
148	```mermaid-example
149	---
150	config:
151	look: handDrawn
152	theme: neutral
153	---
154	flowchart LR
155	A[Start] --> B{Decision}
156	B -->\|Yes\| C[Continue]
157	B -->\|No\| D[Stop]
158	```
159
160	```mermaid
161	---
162	config:
163	look: handDrawn
164	theme: neutral
165	---
166	flowchart LR
167	A[Start] --> B{Decision}
168	B -->\|Yes\| C[Continue]
169	B -->\|No\| D[Stop]
170	```
171
172	#### Selecting Layout Algorithms
173
174	In addition to customizing the look of your diagrams, Mermaid Chart now allows you to choose different layout algorithms to better organize and present your diagrams, especially when dealing with more complex structures. The layout algorithm dictates how nodes and edges are arranged on the page.
175
176	#### Supported Layout Algorithms:
177
178	- Dagre (default): This is the classic layout algorithm that has been used in Mermaid for a long time. It provides a good balance of simplicity and visual clarity, making it ideal for most diagrams.
179	- ELK: For those who need more sophisticated layout capabilities, especially when working with large or intricate diagrams, the ELK (Eclipse Layout Kernel) layout offers advanced options. It provides a more optimized arrangement, potentially reducing overlapping and improving readability. This is not included out the box but needs to be added when integrating mermaid for sites/applications that want to have elk support.
180
181	#### How to Select a Layout Algorithm:
182
183	You can specify the layout algorithm directly in the metadata section of your Mermaid diagram code. Here’s an example:
184
185	```mermaid-example
186	---
187	config:
188	layout: elk
189	look: handDrawn
190	theme: dark
191	---
192	flowchart TB
193	A[Start] --> B{Decision}
194	B -->\|Yes\| C[Continue]
195	B -->\|No\| D[Stop]
196	```
197
198	```mermaid
199	---
200	config:
201	layout: elk
202	look: handDrawn
203	theme: dark
204	---
205	flowchart TB
206	A[Start] --> B{Decision}
207	B -->\|Yes\| C[Continue]
208	B -->\|No\| D[Stop]
209	```
210
211	In this example, the `layout: elk` line configures the diagram to use the ELK layout algorithm, along with the hand drawn look and forest theme.
212
213	#### Customizing ELK Layout:
214
215	When using the ELK layout, you can further refine the diagram’s configuration, such as how nodes are placed and whether parallel edges should be combined:
216
217	- To combine parallel edges, use mergeEdges: true \| false.
218	- To configure node placement, use nodePlacementStrategy with the following options:
219	- SIMPLE
220	- NETWORK_SIMPLEX
221	- LINEAR_SEGMENTS
222	- BRANDES_KOEPF (default)
223
224	Example configuration:
225
226	```
227	---
228	config:
229	layout: elk
230	elk:
231	mergeEdges: true
232	nodePlacementStrategy: LINEAR_SEGMENTS
233	---
234	flowchart LR
235	A[Start] --> B{Choose Path}
236	B -->\|Option 1\| C[Path 1]
237	B -->\|Option 2\| D[Path 2]
238
239	```
240
241	#### Using Dagre Layout with Classic Look:
242
243	Another example:
244
245	```
246	---
247	config:
248	layout: dagre
249	look: classic
250	theme: default
251	---
252
253	flowchart LR
254	A[Start] --> B{Choose Path}
255	B -->\|Option 1\| C[Path 1]
256	B -->\|Option 2\| D[Path 2]
257
258	```
259
260	These options give you the flexibility to create diagrams that not only look great but are also arranged to best suit your data’s structure and flow.
261
262	When integrating Mermaid, you can include look and layout configuration with the initialize call. This is also where you add the loading of elk.
263