Mermaid 中文网

主题

关于 Mermaid ​

🌐 About Mermaid

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

它是一个基于 JavaScript 的图表和制图工具，可以将受 Markdown 启发的文本定义渲染为动态创建和修改的图表。

🌐 It is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.

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

Mermaid 是一个基于 JavaScript 的图表和作图工具，它使用类似 Markdown 的文本定义和渲染器来创建和修改复杂的图表。Mermaid 的主要目的是帮助文档跟上开发的步伐。

🌐 Mermaid is a JavaScript based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams. The main purpose of Mermaid is to help documentation catch up with development.

Doc-Rot 是一个困境，Mermaid 可以帮助解决。

绘图和文档会消耗开发者宝贵的时间，而且很快就会过时。但没有图表或文档会破坏生产力，并影响组织的学习能力。
Mermaid 通过让用户创建容易修改的图表来解决这个问题，它还可以成为生产脚本（以及其他代码部分）的一部分。

Mermaid 甚至允许非程序员通过 Mermaid Live Editor 轻松创建详细的图表。
教程 提供了视频教程。

在你喜欢的应用中使用 Mermaid，查看 社区集成 列表。

🌐 Use Mermaid with your favorite applications, check out the list of Community Integrations.

关于 Mermaid 以及它的一些基本用法的更详细介绍，请参考 新手指南 和 使用方法。

🌐 For a more detailed introduction to Mermaid and some of its more basic uses, look to the Beginner's Guide and Usage.

🌐 CDN | 📖 文档 | 🙌 贡献 | 🔌 插件

🖖 保持稳定的节奏：mermaid 需要更多合作者。

🏆 Mermaid 被提名并赢得了 JS 开源奖 (2019) 的“最令人兴奋的技术应用”类别！！！

感谢所有参与的人，提交拉取请求的人，回答问题的人，特别感谢 Tyler Long 帮助我维护这个项目 🙏

我们的 PR 视觉回归测试由 Argos 提供支持，感谢他们慷慨的开源计划。它让审查包含视觉更改的 PR 变得轻而易举。

🌐 Our PR Visual Regression Testing is powered by Argos with their generous Open Source plan. It makes the process of reviewing PRs with visual changes a breeze.

在我们的发布流程中，我们非常依赖使用 applitools 进行的视觉回归测试。Applitools 是一项非常棒的服务，使用起来简单，并且能够轻松与我们的测试集成。

🌐 In our release process we rely heavily on visual regression tests using applitools. Applitools is a great service which has been easy to use and integrate with our tests.

图表类型 ​

🌐 Diagram Types

流程图 ​

🌐 Flowchart

时序图 ​

🌐 Sequence diagram

甘特图 ​

🌐 Gantt diagram

类图 ​

🌐 Class diagram

Git 图 ​

🌐 Git graph

实体关系图 - ❗ 实验性 ​

🌐 Entity Relationship Diagram - ❗ experimental

用户旅程图 ​

🌐 User Journey Diagram

象限图 ​

🌐 Quadrant Chart

XY 图表 ​

🌐 XY Chart

安装 ​

🌐 Installation

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

了解更多关于 Mermaid 的语法也会很有帮助。

内容分发网络 ​

🌐 CDN

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

选择一个版本：

🌐 To select a version:

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

🌐 Replace <version> with the desired version number.

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

部署 Mermaid ​

🌐 Deploying Mermaid

部署 Mermaid：

🌐 To Deploy Mermaid:

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

Mermaid API： ​

🌐 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 图表。

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

相关项目 ​

🌐 Sibling projects

求助请求 ​

🌐 Request for Assistance

事情越来越多，我很难跟上。如果我们能组建一个核心开发团队来合作推动 mermaid 的未来发展，那就太好了。

🌐 Things are piling up and I have a hard time keeping up. It would be great if we could form a core team of developers to cooperate with the future development of mermaid.

作为该团队的一员，你将获得对代码库的写入权限，并在回答问题和处理问题时代表该项目。

🌐 As part of this team you would get write access to the repository and would represent the project when answering questions and issues.

我们可以一起继续进行类似以下的工作：

🌐 Together we could continue the work with things like:

  • 添加更多类型的图表，如思维导图、ERT图等。
  • 改进现有图表

如果你想参与，别犹豫，随时联系我！

🌐 Don't hesitate to contact me if you want to get involved!

贡献者 ​

🌐 Contributors

Mermaid 是一个不断发展的社区，并且始终欢迎新的贡献者。有很多不同的方式可以提供帮助，我们一直在寻找更多的帮手！如果你想知道从哪里开始贡献，可以看看这个问题。

🌐 Mermaid is a growing community and is always accepting new contributors. There's a lot of different ways to help out and we're always looking for extra hands! Look at this issue if you want to know where to start helping out.

关于如何贡献的详细信息可以在贡献指南中找到。

🌐 Detailed information about how to contribute can be found in the contribution guideline.

要求 ​

🌐 Requirements

  • volta 用于管理 Node 版本。
  • Node.js。volta install node
  • pnpm 包管理器。volta install pnpm

开发安装 ​

🌐 Development Installation

bash
git clone git@github.com:mermaid-js/mermaid.git
cd mermaid
# npx is required for first install as volta support for pnpm is not added yet.
npx pnpm install
pnpm test

代码检查 ​

🌐 Lint

sh
pnpm lint

我们使用 eslint。 我们建议你安装 编辑器插件 来获得实时的代码检查结果。

🌐 We use eslint. We recommend you to install editor plugins to get real time lint result.

测试 ​

🌐 Test

sh
pnpm test

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

🌐 Manual test in browser: open dist/index.html

发布 ​

🌐 Release

对于那些有权限这样做的人：

🌐 For those who have the permission to do so:

更新 package.json 中的版本号。

🌐 Update version number in package.json.

sh
npm publish

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

🌐 The above command generates files into the dist folder and publishes them to npmjs.com.

安全与防护图 ​

🌐 Security and safe diagrams

对于公共网站来说，从互联网上获取用户文本并将其存储以便在稍后阶段在浏览器中呈现是有风险的。原因在于用户内容可能包含嵌入的恶意脚本，当数据被呈现时这些脚本就会运行。对于 Mermaid 来说，这是一种风险，尤其是因为 Mermaid 图表包含许多在 HTML 中使用的字符，这使得标准的清理方法不可用，因为它也会破坏图表。我们仍然会努力清理传入的代码并不断改进这个过程，但很难保证不存在漏洞。

🌐 For public sites, it can be precarious to retrieve text from users on the internet, storing that content for presentation in a browser at a later stage. The reason is that the user content can contain embedded malicious scripts that will run when the data is presented. For Mermaid this is a risk, specially as mermaid diagrams contain many characters that are used in html which makes the standard sanitation unusable as it also breaks the diagrams. We still make an effort to sanitize the incoming code and keep refining the process but it is hard to guarantee that there are no loop holes.

作为对拥有外部用户的网站的额外安全级别，我们很高兴推出一个新的安全级别，在该级别下，图表将在沙箱 iframe 中呈现，从而防止代码中的 JavaScript 被执行。这是提升安全性的一大进步。

🌐 As an extra level of security for sites with external users we are happy to introduce a new security level in which the diagram is rendered in a sandboxed iframe preventing JavaScript in the code from being executed. This is a great step forward for better security.

不幸的是，你不能既吃蛋糕又保留蛋糕，在这种情况下，这意味着一些交互功能会被阻止，同时可能的恶意代码也会被阻止。

🌐 Unfortunately you cannot have a cake and eat it at the same time which in this case means that some of the interactive functionality gets blocked along with the possible malicious code.

报告漏洞 ​

🌐 Reporting vulnerabilities

如需报告漏洞，请发送电子邮件至 security@mermaid.live，附上问题描述、你复现问题的步骤、受影响的版本，以及如果已知的话，针对该问题的缓解措施。

🌐 To report a vulnerability, please e-mail security@mermaid.live with a description of the issue, the steps you took to create the issue, affected versions, and if known, mitigations for the issue.

感谢 ​

🌐 Appreciation

Knut Sveidqvist 的简短说明：

🌐 A quick note from Knut Sveidqvist:

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

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

_ 感谢 Tyler Long，自 2017 年 4 月起一直是我们的合作伙伴。_

_ 感谢不断壮大的贡献者名单，将项目带到今天的高度！_

Mermaid 是由 Knut Sveidqvist 创建的，用于更简便的文档编写。

🌐 Mermaid was created by Knut Sveidqvist for easier documentation.

Opens in mermaid.ai