Mermaid 用户指南

¥Mermaid User Guide

Mermaid 由三部分组成

¥Mermaid is composed of three parts

1. 部署

   ¥Deployment

2. 语法

   ¥Syntax

3. 配置

   ¥Configuration

本节讨论部署 Mermaid 的不同方法。

¥This section talks about the different ways to deploy Mermaid.

如果你是初学者：

¥If you are a beginner:

• 查看 图语法 页面

  ¥Check out the Diagram Syntax page

• 查看 教程 页面

  ¥Check out the Tutorials page

Mermaid 的使用方法

¥Ways to use Mermaid

1. 使用 Mermaid 实时编辑器

   ¥Using the Mermaid Live Editor

2. 使用 Mermaid 图表编辑器

   ¥Using the Mermaid Chart Editor

3. 使用 Mermaid 插件和集成

   ¥Using Mermaid Plugins and Integrations

4. 调用 Mermaid JavaScript API

   ¥Calling the Mermaid JavaScript API

5. 添加 Mermaid 作为依赖

   ¥Adding Mermaid as a dependency

要了解更多信息，请访问 用法 页面。

¥To learn more, visit the Usage page.

1. 使用 Mermaid 实时编辑器

¥ Using the Mermaid Live Editor

可在 Mermaid 在线编辑器 网站上获取。

¥Available at the Mermaid Live Editor website.

特性

¥Features

• 图表代码

¥• Diagram Code

在 Code 面板中，编写或编辑 Mermaid 代码，并立即在图表面板中 Preview 渲染结果。

¥In the Code panel, write or edit Mermaid code, and instantly Preview the rendered result in the diagram panel.

以下是 Mermaid 代码及其渲染结果的示例：

¥Here is an example of Mermaid code and its rendered result:

• 配置

¥• Configurations

Configuration 面板中提供了配置选项。这些选项将应用于 Preview 面板中的图表。

¥Configuration options are available in the Configuration panel. The options are applied to the diagram in the Preview panel.

要了解更多信息，请访问 配置参考 页面

¥To learn more, visit the Configuration Reference page

• 编辑历史记录

¥• Editing History

你的代码将自动保存并显示在 History 部分的 Timeline 选项卡中。每分钟都会保存编辑内容，并且只能查看最后 30 条编辑内容。

¥Your code will be autosaved and appear in the Timeline tab of the History section. Edits are saved every minute and only the last 30 edits are viewable.

或者，你可以通过单击 History 部分中的 Save 图标来手动保存代码。

¥Alternatively, you can manually save code by clicking on the Save icon from the History section.

信息

历史记录仅存储在浏览器存储中。

• 保存图表

¥• Saving a diagram

有多种方法可以保存 Actions 部分的图表：

¥There are multiple ways of saving your diagram from the Actions section:

• 导出 PNG

  ¥export PNG

• 导出 SVG

  ¥export SVG

• 导出为 Markdown

  ¥export as Markdown

• 编辑图表

¥• Editing your diagrams

要编辑图表，你可以将现有 Mermaid 图表代码复制粘贴到 Live Editor 的 Code 部分。

¥To edit your diagram, you can copy paste existing Mermaid diagram code into the Code section of the Live Editor.

或者：

¥Or:

• 从头开始创建一个新图表

  ¥create a new diagram from scratch

• 使用 Sample Diagrams 部分的示例图

  ¥use a Sample Diagram from the Sample Diagrams section

• 从 Gists 加载

¥• Loading from Gists

你创建的 Gist 应该有一个 code.mmd 文件和一个可选的 config.json，类似于此 example。

¥The Gist you create should have a code.mmd file and optionally a config.json, similar to this example.

信息

要了解 Gists，请访问 Creating gists 上的 GitHub 文档页面。

创建 Gist 后，将 Gist URL 复制粘贴到 Actions 部分的相应字段中，然后单击 Load Gist 按钮。

¥Once you have created a Gist, copy paste the Gist URL into the respective field in the Actions section and click on the Load Gist button.

以下是将 Gist 加载到编辑器中的示例：

¥Here is an example of a Gist being loaded into the Editor:

https://mermaid.live/edit?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a

并且，这是上面示例的图表视图：

¥And, here is the diagram view from the above example:

https://mermaid.live/view?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a

2. 使用 Mermaid 图表编辑器

¥ Using the Mermaid Chart Editor

可在 Mermaid 图表 网站上获取。

¥Available at the Mermaid Chart website.

Mermaid Chart 是一个基于 Web 的图表编辑器，允许你在浏览器中创建和编辑图表。它是由 Mermaid 背后的团队构建的。

¥Mermaid Chart is a web-based diagram editor that allows you to create and edit diagrams in your browser. It is built by the team behind Mermaid.

特点包括：

¥Features include:

• 人工智能绘图

  ¥AI diagramming

• 协作和多用户编辑

  ¥Collaboration & multi-user editing

• 贮存

  ¥Storage

• 和更多

  ¥and more

要了解更多信息，请访问文档生态系统部分中的 Mermaid 图表页面。

¥To learn more, visit the Mermaid Chart page in the Ecosystem section of the documentation.

或者去 Mermaid 图表网站 注册一个免费账户。

¥Or go to the Mermaid Chart website to sign up for a Free account.

3. 使用 Mermaid 插件

¥ Using Mermaid Plugins

Mermaid 插件

¥Mermaid Plugins

你可以使用插件从流行的应用中生成 Mermaid 图。

¥You can generate Mermaid diagrams from within popular applications using plug-ins.

有关 Mermaid 插件和集成的列表，请访问 集成页面。

¥For a list of Mermaid Plugins and Integrations, visit the Integrations page.

Mermaid 图表插件

¥Mermaid Chart Plugins

Mermaid 图表插件可用于：

¥Mermaid Chart plugins are available for:

• ChatGPT

• JetBrains IDE

• 微软 PowerPoint

  ¥Microsoft PowerPoint

• 微软 Word

  ¥Microsoft Word

• Visual Studio Code

要了解更多信息，请访问 Mermaid 图表插件 页面。

¥To learn more, visit the Mermaid Chart Plugins page.

原生 Mermaid 支持

¥Native Mermaid Support

对于支持 markdown 的应用（例如 GitHub 和 GitLab），你可以通过制作 mermaid 代码块来添加 Mermaid 图。

¥For apps that support markdown (e.g. GitHub and GitLab), you can add Mermaid diagrams by making a mermaid code block.

The following code-block will be rendered as a Mermaid diagram:

```mermaid
flowchart LR
  A --> B
```

4. 调用 Mermaid JavaScript API

¥ Calling the Mermaid JavaScript API

此方法可用于任何常见的 Web 服务器，例如 Apache、IIS、Nginx 和 Node Express。

¥This method can be used with any common web server like Apache, IIS, Nginx, and Node Express.

你还需要像 Notepad++ 这样的文本编辑工具来生成 html 文件。然后由 Web 浏览器部署，即 Firefox、Chrome、Safari。

¥You will also need a text editing tool like Notepad++ to generate an html file. It is then deployed by a web browser, i.e. Firefox, Chrome, Safari.

信息

不支持 Internet Explorer。

该 API 的工作原理是从源 mermaid.js 提取渲染指令，以便在页面上渲染图表。

¥The API works by pulling rendering instructions from the source mermaid.js in order to render diagrams on the page.

Mermaid API 的要求

¥Requirements for the Mermaid API

在写入 html 文件时，我们在 html code 内部给了 web browser 两条指令：

¥When writing the html file, we give two instructions inside the html code to the web browser:

A。 我们要创建的图表的 Mermaid 代码。

¥a. The Mermaid code for the diagram we want to create.

b. 通过 mermaid.esm.mjs 或 mermaid.esm.min.mjs 导入 Mermaid 库，以及 mermaid.initialize() 调用，它决定图表的外观并启动渲染过程。

¥b. The importing of the Mermaid library through the mermaid.esm.mjs or mermaid.esm.min.mjs, and the mermaid.initialize() call, which dictates the appearance of diagrams and also starts the rendering process.

示例

¥Examples

• 这是 <pre class="mermaid"> 内嵌入 Mermaid 图定义的示例：

  ¥This is an example of an embedded Mermaid diagram definition inside a <pre class="mermaid">:

<body>
  Here is a mermaid diagram:
  <pre class="mermaid">
        graph TD
        A[Client] --> B[Load Balancer]
        B --> C[Server01]
        B --> D[Server02]
  </pre>
</body>

信息

每个 Mermaid 图表/图形/图表定义都应该有单独的 <pre> 标签。

• 这是 Mermaid 导入和 mermaid.initialize() 调用的示例。

  ¥This is an example of a Mermaid import and the mermaid.initialize() call.

信息

mermaid.initialize() 调用获取 <pre class="mermaid"> 标签中包含的所有定义并将它们渲染为图表。

<body>
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
</body>

信息

Mermaid 中的渲染由 mermaid.initialize() 调用初始化。但是，执行相反的操作可让你控制何时开始使用 mermaid.initialize() 在网页内查找 <pre> 标签。当你认为在执行 mermaid.esm.min.mjs 文件时可能并非所有 <pre> 标签都已加载时，这很有用。

startOnLoad 是 mermaid.initialize() 可以定义的参数之一

¥startOnLoad is one of the parameters that can be defined by mermaid.initialize()

参数	描述	类型	值
startOnLoad	加载时切换渲染	布尔值	真假

在此示例中，通过 CDN 调用 mermaidAPI：

¥In this example, the mermaidAPI is being called through the CDN:

<html>
  <body>
    Here is one mermaid diagram:
    <pre class="mermaid">
            graph TD
            A[Client] --> B[Load Balancer]
            B --> C[Server1]
            B --> D[Server2]
    </pre>

    And here is another:
    <pre class="mermaid">
            graph TD
            A[Client] -->|tcp_123| B
            B(Load Balancer)
            B -->|tcp_456| C[Server1]
            B -->|tcp_456| D[Server2]
    </pre>

    <script type="module">
      import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
      mermaid.initialize({ startOnLoad: true });
    </script>
  </body>
</html>

在此示例中，mermaid.js 在 src 中作为单独的 JavaScript 文件引用：

¥In this example, mermaid.js is referenced in src as a separate JavaScript file:

<html lang="en">
  <head>
    <meta charset="utf-8" />
  </head>
  <body>
    <pre class="mermaid">
            graph LR
            A --- B
            B-->C[fa:fa-ban forbidden]
            B-->D(fa:fa-spinner);
    </pre>
    <pre class="mermaid">
            graph TD
            A[Client] --> B[Load Balancer]
            B --> C[Server1]
            B --> D[Server2]
    </pre>
    <script type="module">
      import mermaid from 'The/Path/In/Your/Package/mermaid.esm.mjs';
      mermaid.initialize({ startOnLoad: true });
    </script>
  </body>
</html>

5. 添加 Mermaid 作为依赖

¥ Adding Mermaid as a dependency

以下是将 Mermaid 添加为依赖的步骤：

¥Below are the steps for adding Mermaid as a dependency:

1. 安装 node v16

   ¥Install node v16

信息

要了解有关下载和安装 Node.js 和 npm 的更多信息，请访问 npm Docs website。

1. 通过以下命令使用 npm 安装 yarn：

   ¥Install yarn using npm with this command:

   npm install -g yarn

2. Yarn 安装后，输入以下命令：

   ¥After yarn installs, enter this command:

   yarn add mermaid

3. 要将 Mermaid 添加为开发依赖，请输入以下命令：

   ¥To add Mermaid as a dev dependency, enter this command:

   yarn add --dev mermaid

结束语

¥Closing note

信息

Mermaid 创建者 Knut Sveidqvist 的评论：- 在 Mermaid 的早期版本中，<script> 标签是在网页的 <head> 部分调用的。如今，我们可以将其放在 <body> 中，如上所示。文档的较旧部分经常反映以前的方式，这种方式仍然有效。