mermaid.js + markdown integration

[williamstein]

Nick Bollweg on the JupyterLab call just now mentioned a cool library https://mermaid-js.github.io/mermaid/#/

There's a markdown-it plugin: https://www.npmjs.com/package/markdown-it-mermaid

It could also just be integrated with our slate/markdown pipeline in a very, very similar way to Katex.

This is worth doing because it provides a nice way to create all types of diagrams via very simple clean ascii text. And it would be very good if official Jupyter also supports it, so notebooks work in both environments.

[williamstein]

Neat live demo here

[williamstein]

Nick Bollweg adds that mermaid.js is supported by github flavored markdown, ie.., right here. Let's see:

stateDiagram-v2
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

[williamstein]

https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

[williamstein]

I'm closing this issue. Upon further reflection I don't think mermaid.js belongs in cocalc. The documentation (in terms of api integration) is "frustrating", the general feel of the library from an integration pointed of view is "dated", the actual look of the svg output diagrams is (to my eye) not super dynamic and impressive like many modern libraries (e.g., chart.js), the mermaid.js library is surprisingly large (in terms of code and deps), and we've never had a request for this from a user. Also, the whole approach of a markdown-like language for making diagrams s probably a bit too esoteric and technical for most of our users (unlike, say github users), and it would likely make more sense to extend our new whiteboard with similar functionality in some cases...

[williamstein]

Interesting new discussion of mermaid here: https://news.ycombinator.com/item?id=31273777

[williamstein]

New PR to add mermaid to JupyterLab https://github.com/jupyterlab/jupyterlab/pull/14102

The argument for it would be "it's part of GFM = github flavored markdown". That is compelling. Also, maybe my evaluation of this was unfair, due to me not fully exploring the options. I'm reopening this.

[bollwyvl]

Yerp: it's not my favorite diagramming solution, but it enjoys native, compatible, extensionless implementations on GitHub, GitLab, HackMD, and draw.io (which also runs in jupyterlab).

A difference from many of those places mentioned: in a computable setting like lab or cocalc where markdown du jour is a valid output, it's interesting to be able to gin up quick views of various data with simple string templating vs installing a dedicated backend library and or learning a specific API.

As to why mermaid: in addition to previous flings, I've toyed with browser versions of graphviz, the sqlite- and fossil-centric pikchr (both c-to-WASM, and run in WebWorkers) and ElkJS (which mermaid can now also ship), and a number of others. Each have their own strengths, to be sure. But ultimately evidence of (continued) maintenance, and mostly breadth of adoption trumped enough concerns to get me to actually do the PR to lab core.

[williamstein]

Thanks as always Nick!!

On Wed, Mar 1, 2023 at 3:12 PM Nicholas Bollweg @.***> wrote:

Yerp: it's not my favorite diagramming solution, but it enjoys native, compatible, extensionless implementations on GitHub, GitLab, HackMD, and draw.io (which also runs in jupyterlab https://github.com/deathbeds/ipydrawio).

A difference from many of those places mentioned: in a computable setting like lab or cocalc where markdown du jour is a valid output, it's interesting to be able to gin up quick views of various data with simple string templating vs installing a dedicated backend library and or learning a specific API.

As to why mermaid: in addition to previous flings https://github.com/bollwyvl/nb-mermaid, I've toyed with browser versions of graphviz https://github.com/deathbeds/jupyterlab_graphviz, the sqlite- and fossil-centric pikchr https://github.com/deathbeds/jupikchr (both c-to-WASM, and run in WebWorkers) and ElkJS https://github.com/jupyrdf/ipyelk (which mermaid can now also ship), and a number of others. Each have their own strengths, to be sure. But ultimately evidence of (continued) maintenance, and mostly breadth of adoption trumped enough concerns to get me to actually do the PR to lab core.

— Reply to this email directly, view it on GitHub https://github.com/sagemathinc/cocalc/issues/5861#issuecomment-1451009363, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAJXS5WM3M6UTGMFAPJJEOLWZ7JVJANCNFSM5TLHGDTA . You are receiving this because you modified the open/close state.Message ID: @.***>

-- -- William Stein

[williamstein]

At https://news.ycombinator.com/item?id=36845714 today I learned about an interesting competitor to mermaidjs called "d2", which is here: https://d2lang.com/

This d2 seems very modern and looks really pretty, especially the sketch mode (see https://d2lang.com/blog/hand-drawn-diagrams):

[williamstein]

There's a web app here that compares mermaidjs to d2 for a bunch of examples:

https://text-to-diagram.com/?example=wiiu&b=mermaid

[williamstein]

The most interesting advantage to me of d2 is integrated support for:

• latex formulas
• markdown everywhere
• code with syntax highlighting

[williamstein]

Just to be clear: I want to support both, for compat with github, and because they are both cool in their own ways.