Mermaid.js 凭借一己之力,提升了技术博客内的时序图/类图等 UML 图表的覆盖率。

文档里这句话道出了这个项目的存在意义:

There is no explanation like a Good Diagram - 一图胜千言

在 Web 技术大行其道的今天,Electron 蚕食传统桌面客户端技术的市场。使用 JavaScript 写就的 Mermaid.js 目前已成为各种轻量技术文档编辑器中的一个事实标准模块。

从一个入门开发者和使用者角度看这个项目

第一个 commit 是在 14 年 12月 底, 一开始实现的是 sequenceDiagram。

它的图表 DSL 借鉴了许多开源产品,例如 PlantUML / js-sequence-diagrams 等,但又有各种改进(例如添加元素 onclick 事件回调这样浏览器环境特有的需求)。

Mermaid.js 本身追求代码实现以及使用上的简洁易懂。作者本人最早开始这个兴趣项目是为了做出一个有趣的产品,满足和自己一样的人们的需求。并不是为了炫技以及升职加薪(有些 KPI 项目咱们也就不说什么了)。在开发方向和技术栈的选择上,并没有陷入前端圈的时髦风潮陷阱,一直保持着“简单能用就行”的准则。

简单好用,是它成功的原因。

作为一个想帮它解决小问题的开发者,不需要理解什么复杂宏伟的分层设计,照着代码入口看就能理解工作原理。作为一个使用者,不需要繁复的设定参数,只要一个简单的 <script> 标签引入,然后调用 mermaid.initialize({startOnLoad:true}) 函数即可见证效果。

项目结构

中期的 Mermaid.js 代码分层大概是这样的,实际上,图表实现层对布局和绘制层的调用比较直接和混乱,基本上一种图表一种特化(怎么画线、箭头等)实现方式。

使用的一些第三方库

  • dagre - Graph layout for JavaScript,包含多种图布局算法实现的库,本身不包含渲染层,但可通过 dagre-d3 调用 d3.js 完成绘制。
  • graphlib,如名字所示,是一个 JavaScript 写的关于图(Graph) 的工具库,包括基础的用于构建图的对象接口,以及一些图算法。详情可见其 API-Reference
  • D3.js,前端数据可视化无人不知的库,作者在可视化和交互设计上有许多优秀的论文以及项目。Mermaid.js 本身目标不是数据可视化,主要是用 d3 和一些扩展库来操作 DOM。

近期的发展

向社区寻求帮助

一年前,作者在 issues 里向社区求助 Collaborators wanted! · Issue #866 · mermaid-js/mermaid,将 issue 分类 / 小 bug 修复等轻量工作委托给社区热心开发者。

这是一个流行的开源产品一定会经历的阶段,毕竟即便搭上作者所有的业余时间,仅凭一个人肯定是无法面对各种问题和 feature request 的。因此在项目名声鹊起之时,作者很有必要考虑如何建立友好互动的社区,包括但不限于给出 Github CONTRIBUTOR.md 指南、建立实时讨论组(Slack/Gitter 之类)、线下分享会等。

Generic rendering engine

最早有人提 issue 问是否可以有通用渲染引擎来满足非常规 uml 图表的绘制需求,作者也意识到了每个图表的 renderer 重复做一些事情且重复修类似 bug 的痛苦之处,开始思考合理划分通用渲染和单独图表逻辑。

2020/5/5 提出 isssue Create generic rendering engine,月底完成合入主分支。之后逐步给主要图表添加 v2 版本,如 stateDiagram-v2 与旧版共存。

作者是个务实的人,当前阶段的渲染层并不着急对过去内部概念推倒重建,而是在逐步改写的第一阶段,先包装好对 dagre 的调用和增强。