图表语法

【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 Live Editor 中找到图表示例，这里也是一个非常好的练习区域。

【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. The only exception to this a Frontmatter configuration.】

行注释可以忽略 '%% ' 之后该行上的任何内容。

【Line comments can ignore anything on the line after '%% '.】

未知的单词和拼写错误会破坏图表，而参数则会悄悄地失效。

【Unknown words and misspellings will break a diagram, while parameters silently fail.】

示例：下面的代码是一个实体关系图，由 erDiagram 声明指定。接下来是对图中所表示的不同 实体 的定义。

入门指南 部分也可以提供一些 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.】

Diagram Breakers	Reason	Solution
Comments
%%{``}%%	Similar to Directives confuses the renderer.	In comments using %%, avoid using "{}".
Flow-Charts
'end'	The word "End" can cause Flowcharts and Sequence diagrams to break	Wrap them in quotation marks to prevent breakage.
Nodes inside Nodes	Mermaid gets confused with nested shapes	wrap them in quotation marks to prevent breaking

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

这些技术在功能上是等效的，但适合不同的部署场景。

【Each of these techniques are functionally equivalent, but better for different deployments.】

initialize() 调用

【The initialize() call】

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

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

图表代码的前置内容

【Frontmatter for diagram code】

Frontmatter 是在代码开头添加 YAML 元数据的术语。这允许在渲染图表之前重新配置图表。你可以通过在定义前后各加一行 --- 来传递 Frontmatter 元数据。这个“三级破折号”必须是第一行唯一的字符。

【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.】

页眉使用 YAML 语法。它要求任何缩进保持一致，并且设置区分大小写。Mermaid 会静默忽略拼写错误，但格式不正确的参数会导致图表无法显示。

【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.】

指令

【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.】

可用外观：

• 手绘风格：为了更具个人化和创意感，手绘风格为你的图表带来一种素描般的效果。这种风格非常适合非正式场合，或者当你想为图表添加一些个性时使用。
• 经典风格：如果你更喜欢传统的 Mermaid 风格，经典风格保持了许多用户熟悉的原始外观。它非常适合跨项目保持一致性，或者当你希望保持熟悉的美学时使用。

如何选择造型：

你可以通过在你的 Mermaid 图表代码的元数据部分添加 look 参数来选择一个样式。示例如下：

【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 图表现在还允许你选择不同的布局算法，以更好地组织和展示图表，尤其是在处理更复杂的结构时。布局算法决定了页面上节点和边的排列方式。

【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 长期使用的经典布局算法。它在简单性和视觉清晰度之间提供了良好的平衡，非常适合大多数图表。
• ELK：对于那些需要更复杂布局功能的人，尤其是在处理大型或复杂图表时，ELK（Eclipse Layout Kernel）布局提供了高级选项。它可以实现更优化的排列，可能减少重叠并提高可读性。这不包含在默认包中，需要在为希望支持 ELK 的网站/应用集成 Mermaid 时额外添加。

如何选择布局算法：

【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。
• 要配置节点放置，请使用 nodePlacementStrategy，选项如下：
  • SIMPLE
  • NETWORK_SIMPLEX
  • LINEAR_SEGMENTS
  • BRANDES_KOEPF（默认）

示例配置：

---
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]

使用 Dagre 布局与经典外观：

【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.】