Mermaid中文文档

Appearance

关于 Mermaid ​

Mermaid 让你可以使用文本和代码创建图表和可视化。

Mermaid 是一个基于 JavaScript 的图表和制图工具，使用 Markdown 风格的文本定义和渲染器来创建和修改复杂的图表。Mermaid 的主要目的是帮助文档跟上开发进度。

如果你对 Markdown 熟悉，学习 Mermaid 的语法 应该没有问题。

即使是非程序员也可以通过 Mermaid 在线编辑器 轻松创建详细的图表。

图表类型 ​

流程图 ​

Code:
mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

序列图 ​

Code:
mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop HealthCheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

甘特图 ​

Code:
mermaid
gantt
dateFormat  YYYY-MM-DD
title Adding GANTT diagram to mermaid
excludes weekdays 2014-01-10

section A section
Completed task            :done,    des1, 2014-01-06,2014-01-08
Active task               :active,  des2, 2014-01-09, 3d
Future task               :         des3, after des2, 5d
Future task2               :         des4, after des3, 5d

类图 ​

Code:
mermaid
classDiagram
Class01 <|-- AveryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label

Git 图表 ​

Code:
mermaid
    gitGraph
       commit
       commit
       branch develop
       commit
       commit
       commit
       checkout main
       commit
       commit

实体关系图 - ❗ 实验性功能 ​

Code:
mermaid
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

用户旅程图 ​

Code:
mermaid
journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me

象限图 ​

Code:
mermaid
quadrantChart
    title Reach and engagement of campaigns
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 We should expand
    quadrant-2 Need to promote
    quadrant-3 Re-evaluate
    quadrant-4 May be improved
    Campaign A: [0.3, 0.6]
    Campaign B: [0.45, 0.23]
    Campaign C: [0.57, 0.69]
    Campaign D: [0.78, 0.34]
    Campaign E: [0.40, 0.34]
    Campaign F: [0.35, 0.78]

XY 图 ​

Code:
mermaid
xychart-beta
    title "Sales Revenue"
    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
    y-axis "Revenue (in $)" 4000 --> 11000
    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]

安装 ​

详细的指南和示例可以在 使用 中找到。

了解 Mermaid 的 语法 也会很有帮助。

CDN ​

https://cdn.jsdelivr.net/npm/mermaid@<version>/dist/

选择版本：

将 <version> 替换为所需的版本号。

最新版本：https://cdn.jsdelivr.net/npm/mermaid@11

部署 Mermaid ​

部署 Mermaid 的步骤：

  1. 你需要安装 node v16，随之会安装 npm
  2. 安装 Mermaid
    • NPM: npm i mermaid
    • Yarn: yarn add mermaid
    • Pnpm: pnpm add mermaid

Mermaid API: ​

要在没有打包工具的情况下部署 Mermaid，请在 HTML 中插入一个带绝对地址的 script 标签和一个 mermaid.initialize 调用，示例如下：

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

这样会指令 Mermaid 解析器查找带有 class="mermaid" 的 <div> 或 <pre> 标签。从这些标签中，Mermaid 会尝试读取图表定义并将其渲染为 SVG 图表。

示例可以在 其他示例 找到。

贡献者 ​

良好第一个问题贡献者提交记录

Mermaid 是一个不断壮大的社区，始终欢迎新的贡献者。帮助的方法有很多，我们也总是需要额外的手！如果你想知道从哪里开始，可以查看 这个问题。

要求 ​

  • volta 来管理节点版本。
  • Node.js。 volta install node
  • pnpm 包管理器。 volta install pnpm

开发安装 ​

bash
git clone git@github.com:mermaid-js/mermaid.git
cd mermaid
# npx 是第一次安装的必要条件，因 volta 尚未支持 pnpm。
npx pnpm install
pnpm test

Lint ​

sh
pnpm lint

我们使用 eslint。 我们建议你安装 编辑器插件 来获取实时的 lint 结果。

测试 ​

sh
pnpm test

在浏览器中手动测试：打开 dist/index.html

发布 ​

对于那些有权限的人：

更新 package.json 中的版本号。

sh
npm publish

上述命令会在 dist 文件夹中生成文件并将其发布到 npmjs.com。

安全和安全图表 ​

对于公共网站，从互联网上的用户检索文本并在稍后阶段存储该内容以供在浏览器中展示可能是危险的。原因在于用户内容可能包含嵌入的恶意脚本，这些脚本会在数据展示时运行。对于 Mermaid 而言，这是一个风险，特别是因为 Mermaid 图表包含许多在 HTML 中使用的字符，这使得标准的清理方法失效，因为它也会破坏图表。我们仍然努力清理进入的代码并不断完善这个过程，但很难保证没有漏洞。

作为具有外部用户的网站的额外安全级别，我们很高兴引入一种新的安全级别，在这种情况下，图表在一个沙箱 iframe 中渲染，从而防止代码中的 JavaScript 被执行。这是提高安全性向前迈出的重要一步。

不幸的是，你不能同时拥有蛋糕和吃蛋糕，从这个角度来说，这意味着部分交互功能也会被阻止，还有可能的恶意代码。

报告漏洞 ​

要报告漏洞，请发送电子邮件至 security@mermaid.live，描述问题、你采取的步骤以重现该问题、受影响的版本，并在已知的情况下提供针对该问题的缓解方案。

感谢 ​

来自 Knut Sveidqvist 的简短致谢：

非常感谢 d3 和 dagre-d3 项目提供图形布局和绘图库！

感谢 js-sequence-diagram 项目使用序列图的语法。感谢 Jessica Peter 提供的灵感和甘特图渲染的起点。

感谢 Tyler Long，他自 2017 年 4 月以来一直是合作者。

感谢日益增长的 贡献者 名单，使项目走到今天这一步！

Mermaid 是由 Knut Sveidqvist 创建的，旨在简化文档。