轻松记录您
灵感和创意

Markdown 式文字转流程图:Mermaid

Matrix 是少数派的写作社区,我们主张分享真实的产品体验,有实用价值的经验与思考。我们会不定期挑选 Matrix 最优质的文章,展示来自用户的最真实的体验和观点。

文章代表作者个人观点,少数派仅对标题和排版略作修改。

「码图」而不是「画图」?

许多工作者的日常工作中,除了写字记录,有时还会需要画一些简单的「示意图」,这些示意图会让我们的文档或报告变得形象生动,便于理解,例如下面这些图:

流程图结构关系图进度图或甘特图业务序列图

如果我们恰好同时对 Markdown 的「标记式」记录方法高度认可的话,那么有没有想过使用类似 Markdown 形式的语言,快速 「写」一个「流图」 出来?

说到 Markdown, 可能已经是很多朋友熟悉的一种记录语言了。在互联网时代,Markdown 被广泛普及运用。很多人用 Markdown 写博客,写日志,写备忘,网上也有一堆支持 Markdown 的写作工具,例如:熊掌记(bear),ia Writer, Ulysses, Day One,甚至 印象笔记 也在近几年开始支持 Markdown 语法。对于不少追求效率的朋友来说,Markdown 是近来文字记录领域中难以忽视的方案。

那么在「绘制流图」的领域当中,也有类似 Markdown 的方案呢?

细细想来,流图或关系图,主要强调的是 拓扑关系,流向,节点内容,而不是一些花哨的排版。 这点和 Markdown 秉承的「重内容,重结构,轻排版」的思路有不谋而合之处。 所以,火箭君这次想介绍的就是,「流图界」的 Markdown 语言,也被称之为 Mermaid 语言。

本文的目的,就在于给大家一个入门的介绍,帮助大家认识到 Mermaid 的威力以及上手融入工作的方法。

Mermaid 的具体文档和范例都有专门的官方网站介绍,文章最后会列出参考出处,需要深入了解的话可以细细挖掘,惊喜不断。

Mermaid 的好处

易于编辑和生成图画

通过 Mermaid,我们不用专门的流图工具(例如:微软的 Visio),我们需要编辑的只是文本,因此不少现成的 Markdown 编辑器都可以用上,如果不看渲染结果,仅作编辑的话,普通文本编辑器都能胜任。

一个简单的例子,短短几行就能生成一个流图:

graph TD;

A–>B;

A–>C;

B–>D;

C–>D;

一个简单流图的渲染结果

符合火箭君主张的「开放文件理念」

Mermaid 和 Markdown 一样,都是纯文本格式存储的语言。纯文本文件打破了很多软件封闭格式的限制,更加利于用户掌握自己的内容。也易于我们 存储,解析,发送文件内容,而不是受制于特定应用的软件或网站平台。

如果我们有过某些领域下载文献的经验就会看到,许多宝贵的 paper 都被加工成 一些特定加密格式的文件,只有 XX 阅读器可以浏览。 XX 阅读器可能会打广告可能会要求我们续费,然而即使这样,我们的资料仍旧对我们不透明,哪天 XX 阅读器不高兴的话,我们下载的资料就是乌有。 连「有和无」都成问题, 更谈不上信息利用分析和检索了。 这也是有感而发,前两天刚有小伙伴咨询有无办法将这种格式 批量转换成 PDF(PDF 是一种开放标准格式,几乎对所有人透明)。

天然的 Web 友好特性

Mermaid 的核心是一个基于 JS 的解析库,这意味着我们可以把 Mermaid 文本,直接嵌入网页中,而访问者就能 直接看到 渲染后的流图了。

顺便说一下,Mermaid 的 JS 解析库,被评为 2019 年 JS Open Source Awards 「The most exciting use of technology」分类下的大奖。

以后,只要页面略作调整,就能在 公司官网,在线创作平台,在线文档,在线笔记 之类的网页里嵌入流图了。而以往我们需要这样做:

通过画图软件生成图片截图编辑上传贴图到图床或云存储将图片引用地址嵌入网页或文档

而现在,利用 Mermaid 只要一步(编辑 Mermaid 代码)就可以了。

Mermaid 登场及用法

我们在哪里能写 Mermaid?

我们已经知道,Mermaid 本质是一种标记语言,借由一个解析库 将文本 「翻译渲染」成「图画」。

虽然通过一个纯文本编辑器,例如:写字板,我们可以撰写 Mermaid 文本,但显然不能指望这样就可以「渲染」出「绘图」来。这和 Markdown 的原理是一样的,渲染需要专门的编辑器。 好消息是,Mermaid 已经被很多 Markdown 编辑器直接或间接支持。 也就是说直接用现有的 Markdown 编辑器就可以上手一试了,几乎没有额外负担。

这里是部分支持 Mermaid 的编辑器

印象笔记 Markdown 笔记有道云笔记(未实测,希望大家补充纠正)Typora (火箭君推荐)MWeb(未实测,希望大家补充纠正)VSCode + Mermaid 插件Atom + Mermaid 插件MermaidJS 官方网页版 编辑器 (后文有参考链接)

需要注意的是,由于 Mermaid 本身还在发展,并非所有特性都能被所有 Markdown 编辑器支持。不过,常见的流图编辑模式已经比较成熟,大多被支持。至于具体渲染效果如何,我们还是要以编辑器的实际输出为准。

印象笔记在 Markdown 笔记中 生成的 Mermaid 图

Mermaid 支持哪些图?

目前这个 Mermaid 主要可支持的「绘图」有:

流图 (Flow)序列图 (Sequence)甘特图(Gantt)类图(Class)状态迁移图(State)饼分图(Pie)

由于 Mermaid 本身也在逐步发展,后续还会有各种各样的图被引入进来。 例如:时间轴日记(User Journey),类图(Class),实体映射图(数据词典定义时常用)

MermaidJS官网的展示例子

还是要再次提请注意,不是所有的 Markdown 编辑器都支持所有的绘图类型。即使编辑器支持渲染,渲染出的效果也各不相同。这点就像早期不同的浏览器会选择性支持部分的 HTML 网页标准一样。目前来看,主流的 Markdown 编辑器,至少会支持 「流图」和「序列图」,至于其它类型就要看运气了。

上文提到的「Mermaid 官方网页版 编辑器 」是一个不错的参考,从这个在线编辑器里,我们可以看到目前 Mermaid 全部支持的类型,以及目前处于「实验室」阶段的类型。

如何「码」第一个图?

首先,我们要打开一个支持 Mermaid 的 Markdown 编辑器。,这里以 火箭君目前最爱的 Typora 编辑器为例。

我们知道 Markdown 语法能支持 代码块,所谓代码块就是一种特殊段落,其中的文字,会按照特殊的语法进行处理显示。

一般来说,例如 网页标记语言,编程语言之类代码块,都会按照语法高亮显示。

普通Markdown「代码块」的显示效果

Mermaid 也采用了 代码块进行展现和渲染。

因此,我们首先需要在编辑器里单独一行内输入 Mermaid ,表示以下是 Mermaid 语言 专属的 代码块。 然后,在 这行下面按照语法,就可以撰写 绘图的脚本了。

我们用「序列图」来描述一个银行存钱的过程,里面有三个角色:

客户银行柜员银行后台

通过序列图,我们可以把存钱的过程如下描述出来:

sequenceDiagram

客户->>银行柜台: 我要存钱

银行柜台->>后台: 改一下这个账户数字哦

后台->>银行柜台: 账户的数字改完了,明天起息

银行柜台->>客户: 好了,给你回单 ,下一位

我们注意到, 只要通过 ->> 和冒号 这种简单的文本标记,就能把各种关系和方向清晰的表达出来了。

Mermaid 的渲染结果如下:

同理,我们再看看,如何画一个简单的「流图」。

首先还是从输入 ` Mermaid 开始

然后输入:

graph TD

A(起床) –> B[洗漱]

B –> C{扔硬币}

C –>|正面朝上| D[喝牛奶]

C –>|反面朝上| E[喝果汁]

我们注意到, 只要也是通过纯文本的箭头符号和括号就能把一段逻辑描述清楚了。

Mermaid 的渲染结果如下:

如果有兴趣的话,我们还可以在上面的例子里自行修改,这样就能轻易扩充出更加复杂的逻辑关系。

哪里有更多的参考?

Mermaid 支持更复杂的玩法,远不止上面列出的这些,但都非常容易被理解,一般不外乎就是各种符号的组合,这点就充分继承了 Markdown 类语言的精髓 。火箭君更喜欢称之为「文字游戏」,通过文字的组合可以表达正文内容以外,更复杂的含义,或者说某种「元信息」(meta info)。

语法参考

Mermaid 详细语法参考可以 参见 Github 上 MermaidJS 项目的文档:

https://mermaid-js.github.io/mermaid/diagrams-and-syntax-and-examples/n00b-syntaxReference.html

渲染主题

除了描述逻辑关系的语法,Memraid 还提供 了简单的「换皮主题」的语法,

通过这套「换皮」语法,我们可以给每个类型的元素更换主题色,例如箭头颜色,例如流程块的背景色…… 特别适合,对绘图的颜值有要求,而且有折腾精神的用户使用。参考语法如下:

https://mermaid-js.github.io/mermaid/getting-started/theming.html

可以自定义各种颜色和效果

在线练手网站

看到这里,如果想立刻上手试试看的话,可以用 MermaidJS 官方网页版 编辑器 立刻行动(相当于一个代码 playground)

在线编辑器,本身就是一个很好的教程,里面已经分门别类列好了各种图的类型,供我们选择。 而且每种图下面都有 Sample 代码,新手上去改改就能看到结果。

https://mermaid-js.github.io/mermaid-live-editor

最后

火箭君相信,需要绘制流图之类的小伙伴们,一般都会有很强的生产力需求,而不太会是仅仅出于「自嗨」,例如:我们需要用一个 「序列图」来描述一段 运营工作流程时,往往希望这个 图能够被讨论,被迭代,最终被分发到 运营人员手上,而不是画出来仅供自我欣赏。

在以往,分享这种专业流图,往往需要用到截图,但是这样难于被编辑。也可以用 Visio 专业软件,当然费用不菲。或者通过云端绘图站点分享,不过需要注册账号,接入 互联网,而且文档难以归档保存在本地。 这些问题,就和当年 Markdown 流行之前,「文字格式排版」遇到的情况很接近。 我们现在也看到了,随着 Markdown 的普及,很多问题迎刃而解,现在 Markdown 是火箭君这里内部文档的标准格式,对外才会用到 Word/PDF 之类(而且部分也是 Markdown 渲染生成出来的)。

额外值得一提的是,Mermaid 有一个在线渲染的服务,我们可以把一段 Mermaid 代码 转换为 URL 网址。这样,我们就可以将 URL 嵌入各种文档,阅读文档时,在线网址将 URL 翻译成图像展现出来。 和普通图片上传的区别是,这个 URL 只是提供 Mermaid 代码,并没有真的上传图像到服务器上,因此也不依赖服务器是否实际存储或删除了我们的图像。这也意味着 URL 可以被其它 Mermaid 渲染服务网站接手从而产生图像。

更简单的做法是,用户双方都使用同种类型的 MD 编辑器,例如 Typora,印象笔记,那么大家交流的效率就会更高。几十采用不同的编辑器,也只是渲染效果不同,语义逻辑应该还是一致的。

总之,Mermaid 作为一个 新兴的标记语言,像极了当年 的 Markdown。假以时日,希望 Mermaid 会变得更加成熟,在有专业需求的领域里,变得更加普及,成为一种「约定俗成」的高效率标准。

未经允许不得转载:坚果云Markdown编辑器 » Markdown 式文字转流程图:Mermaid
分享到: 更多 (0)

坚果云Markdown轻松记录您 灵感和创意

坚果云Markdown下载坚果云Markdown介绍