图语法

¥Diagram Syntax

Mermaid 的语法用于创建图表。你会发现它并不太棘手，一天之内就能学会。接下来的部分将深入探讨每种图表类型的语法。

¥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.

语法与部署和配置一起构成了 Mermaid 的整体。

¥Syntax, together with Deployment and Configuration constitute the whole of Mermaid.

图表示例可以在 Mermaid 在线编辑器 中找到，这也是一个很好的练习区域。

¥Diagram Examples can be found in the Mermaid Live Editor, it is also a great practice area.

语法结构

¥Syntax Structure

人们会注意到，所有图表定义都以图表类型的声明开始，后面是图表及其内容的定义。该声明通知解析器代码应该生成哪种图表。

¥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.

示例：下面的代码用于实体关系图，由 erDiagram 声明指定。下面是其中代表的不同 Entities 的定义。

¥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.

入门 部分还可以提供一些 mermaid 语法的实用示例。

¥The Getting Started section can also provide some practical examples of mermaid syntax.

图解

¥Diagram Breaking

人们应该小心使用一些可能破坏图表的文本或符号。这些文本或符号很少，并且通常只影响特定类型的图表。下表将持续更新。

¥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.

图表破坏者	原因	解决方案
注释
%%{``}%%	类似于 指令 混淆渲染器。	在使用 %% 的注释中，避免使用“{}”。
流程图
'end'	"End" 这个词可能会导致流程图和时序图中断	将它们用引号括起来以防止损坏。
节点内的节点	Mermaid 对嵌套形状感到困惑	将它们用引号括起来以防止破坏

Mermaid 在线编辑器

¥Mermaid Live Editor

现在，你已经了解了不应该添加到图表中的内容，你可以在 Mermaid 在线编辑器 中使用它们。

¥Now, that you've seen what you should not add to your diagrams, you can play around with them in the Mermaid Live Editor.

配置

¥Configuration

配置是 Mermaid 的第三部分，位于部署和语法之后。它涉及在不同部署中定制 Mermaid 的不同方式。

¥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.

如果你有兴趣更改和自定义 Mermaid 图，你可以在此处找到适用于 配置 的方法和值。它包括主题。本节将介绍配置 Mermaid 图的行为和外观的不同方法。以下是最常用的方法，它们都与 Mermaid 部署 方法相关。

¥If you are interested in altering and customizing your Mermaid Diagrams, you will find the methods and values available for Configuration here. It includes themes. This section will introduce the different methods of configuring the behaviors and appearances of Mermaid Diagrams. The following are the most commonly used methods, and they are all tied to Mermaid Deployment methods.

在线编辑器 中的配置部分。

¥Configuration Section in the Live Editor.

你可以在此处编辑某些值以更改图表的行为和外观。

¥Here you can edit certain values to change the behavior and appearance of the diagram.

initialize() 调用

¥The initialize() call

当通过 API 或通过 <script> 标签调用 Mermaid 时使用。

¥Used when Mermaid is called via an API, or through a <script> tag.

指令

¥Directives

允许在渲染图表之前对其进行有限的重新配置。它可以改变图表的字体样式、颜色和其他美学方面。你可以在 %%{ }%% 内传递指令和定义。它可以在图表定义的上方或下方完成。

¥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.

主题操控

¥Theme Manipulation

使用指令更改 主题 的应用。Theme 是 Mermaid 配置中的一个值，它规定了图表的颜色方案。

¥An application of using Directives to change Themes. Theme is a value within Mermaid's configuration that dictates the color scheme for diagrams.

布局和外观

¥Layout and look

我们重新构建了 Mermaid 渲染图表的方式，启用了选择布局和外观等新功能。目前，流程图和状态图支持此功能，并计划将支持扩展到所有图表类型。

¥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.

选择图表外观

¥Selecting Diagram Looks

Mermaid 为你的图表提供了多种风格或“外观”，允许你定制视觉外观以满足你的特定需求或偏好。无论你喜欢手绘还是经典风格，你都可以轻松自定义图表。

¥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.

可用外观：

¥Available Looks:

• 手绘外观：为了获得更个性化、更具创意的感觉，手绘外观为你的图表带来了类似草图的品质。此风格非常适合非正式场合，或者当你想要为图表添加一点个性时。

  ¥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.

• 经典外观：如果你更喜欢传统的 Mermaid 风格，经典外观保留了许多用户熟悉的原始外观。它非常适合跨项目的一致性或当你想要保持熟悉的美感时。

  ¥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.

如何选择外观：

¥How to Select a Look:

你可以通过在 Mermaid 图表代码的元数据部分中添加外观参数来选择外观。以下是示例：

¥You can select a look by adding the look parameter in the metadata section of your Mermaid diagram code. Here’s an example:

选择布局算法

¥Selecting Layout Algorithms

除了自定义图表的外观外，Mermaid Chart 现在还允许你选择不同的布局算法来更好地组织和渲染图表，尤其是在处理更复杂的结构时。布局算法决定了节点和边在页面上的排列方式。

¥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.

支持的布局算法：

¥Supported Layout Algorithms:

• Dagre（默认）：这是 Mermaid 中长期使用的经典布局算法。它在简单性和视觉清晰度之间取得了良好的平衡，使其成为大多数图表的理想选择。

  ¥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.

• ELK:对于那些需要更复杂的布局功能的人，尤其是在处理大型或复杂图表时，ELK（Eclipse 布局内核）布局提供了高级选项。它提供了更优化的排列，可以减少重叠并提高可读性。这不是开箱即用的，但在为需要 elk 支持的站点/应用集成 mermaid 时需要添加。

  ¥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.

如何选择布局算法：

¥How to Select a Layout Algorithm:

你可以直接在 Mermaid 图表代码的元数据部分指定布局算法。以下是示例：

¥You can specify the layout algorithm directly in the metadata section of your Mermaid diagram code. Here’s an example:

在此示例中，layout: elk 行将图表配置为使用 ELK 布局算法，以及手绘外观和森林主题。

¥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.

自定义 ELK 布局：

¥Customizing ELK Layout:

使用 ELK 布局时，你可以进一步优化图表的配置，例如如何放置节点以及是否应组合平行边：

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

• 要组合平行边，请使用 mergeEdges：true | false。

  ¥To combine parallel edges, use mergeEdges: true | false.

• 要配置节点放置，请使用 nodePlacementStrategy 和以下选项：

  ¥To configure node placement, use nodePlacementStrategy with the following options:

  • SIMPLE

  • NETWORK_SIMPLEX

  • LINEAR_SEGMENTS

  • BRANDES_KOEPF（默认）

    ¥BRANDES_KOEPF (default)

示例配置：

¥Example configuration:

---
config:
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: LINEAR_SEGMENTS
---
flowchart LR
  A[Start] --> B{Choose Path}
  B -->|Option 1| C[Path 1]
  B -->|Option 2| D[Path 2]

#### Using Dagre Layout with Classic Look:

另一个示例：

¥Another example:

---
config:
  layout: dagre
  look: classic
  theme: default
---

flowchart LR
A[Start] --> B{Choose Path}
B -->|Option 1| C[Path 1]
B -->|Option 2| D[Path 2]

这些选项使你可以灵活地创建不仅外观精美而且还能最适合数据结构和流程的图表。

¥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.

集成 Mermaid 时，你可以在初始化调用中包含外观和布局配置。这也是你添加 elk 加载的地方。

¥When integrating Mermaid, you can include look and layout configuration with the initialize call. This is also where you add the loading of elk.