Wolfram Cloud Resource Object

Function Resource

Function Repository Resource:

 MermaidCLIOutput

Source Notebook

Returns an image corresponding to a mermaid-js specification via the command line interface of mermaid-js

Contributed by: Anton Antonov

ResourceFunction["MermaidCLIOutput"][s]

invokes Mermaid's Command Line Interface (CLI) with the spec s and imports the result.

ResourceFunction["MermaidCLIOutput"][s,t]

specifies Mermaid's CLI output to be of type t.

ResourceFunction["MermaidCLIOutput"][s,t,copts]

invokes Mermaid's CLI with the options copts.

Details and Options

Mermaid lets you create diagrams and visualizations using text and code.
It is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.
ResourceFunction["MermaidCLIOutput"] uses the Command Line Interface (CLI) to Mermaid's functionalities via the Shell function mmdc.
This means that mmdc (aka "mermaid-cli") have to be installed on the computer executing ResourceFunction["MermaidCLIOutput"].
ResourceFunction["MermaidCLIOutput"] passes a Mermaid spec to mmdc.
The script mmdc generates a PNG, PDF, of SVG file, that file is placed in a temporary directory, and it is imported by ResourceFunction["MermaidCLIOutput"].
By default ResourceFunction["MermaidCLIOutput"] requets mmdc with to generate a PNG image.
If a PDF type is specified, them ResourceFunction["MermaidCLIOutput"] imports the resulting PDF file as a graphics expression. (Using Import[__,"PageGraphics"].)
The first argument can be a string (that is a mermaid-js specification) or a Graph object.

Examples

Basic Examples (2) 

Here is flowchart generate with a Mermaid specification:

In[1]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" graph TD WL --> |ZMQ|Python --> |ZMQ|WL "]
Out[1]=

Here is class diagram that is a Graphics expression:

In[2]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" classDiagram Animal <|-- Duck Animal <|-- Fish Animal <|-- Zebra Animal : +int age Animal : +String gender Animal: +isMammal() Animal: +mate() class Duck{ +String beakColor +swim() +quack() } class Fish{ -int sizeInFeet -canEat() } class Zebra{ +bool is_wild +run() } ", "PDF", ImageSize -> Large]
Out[2]=

Scope (11) 

Additional options can be passed to mmdc with the third argument of MermaidCLIOutput. For example, if the PNG images are with too low resolution then the mmdc"--scale" option can be used:

In[3]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" graph LR WL --> |ZMQ|Python --> |ZMQ|WL ", "PNG", "MermaidOptions" -> "--scale 2"]
Out[3]=

The first argument can be a Graph object -- the corresponding mermaid-js graph is produced. Here is a random graph that has both directed and undirected edges (some edges have tags):

In[4]:=
SeedRandom[45]; gr = GraphUnion[RandomGraph[{3, 2}, DirectedEdges -> True], RandomGraph[{4, 4}, DirectedEdges -> False]]; gr = Graph[ Map[RandomChoice[{#, Append[#, RandomWord[]]}] &, EdgeList[gr]], VertexLabels -> "Name", EdgeLabels -> "EdgeTag"]; gr
Out[5]=

Here is the corresponding mermaid-js image:

In[6]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][gr]
Out[6]=

Here is a top-down version:

In[7]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][gr, "MermaidDirectives" -> "TD"]
Out[7]=

Mermaid has a different type of diagrams: Flowchart, Sequence Diagram, Class Diagram, State Diagram, Entity Relationship Diagram, User Journey, Gantt, Pie Chart, Requirement Diagram, Gitgraph Diagram, and others.

Sequence Diagram:

In[8]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]]["sequenceDiagram Alice->>John: Hello John, how are you? John-->>Alice: Great! Alice-)John: See you later!"]
Out[8]=

Here is Graphics expression of a Class Diagram obtained via a PDF file additionally tweaked to have large image size:

In[9]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" classDiagram Animal <|-- Duck Animal <|-- Fish Animal <|-- Zebra Animal : +int age Animal : +String gender Animal: +isMammal() Animal: +mate() class Duck{ +String beakColor +swim() +quack() } class Fish{ -int sizeInFeet -canEat() } class Zebra{ +bool is_wild +run() } ", "PDF"] // Append[#, ImageSize -> Large] &
Out[9]=

State diagram:

In[10]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" stateDiagram-v2 [*] --> Still Still --> [*] Still --> Moving Moving --> Still Moving --> Crash Crash --> [*] "]
Out[10]=

Entity Relationship Diagram:

In[11]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE-ITEM : contains CUSTOMER }|..|{ DELIVERY-ADDRESS : uses "]
Out[11]=

User Journey -- PNG image is obtained and cropped:

In[12]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" 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 "] // ImageCrop
Out[12]=

Gantt chart:

In[13]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" gantt title A Gantt Diagram dateFormat YYYY-MM-DD section Section A task :a1, 2014-01-01, 30d Another task :after a1 , 20d section Another Task in sec :2014-01-12 , 12d another task : 24d "]
Out[13]=

Pie chart:

In[14]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]]["pie title Pets adopted by volunteers \"Dogs\" : 386 \"Cats\" : 85 \"Rats\" : 15"]
Out[14]=

Requirement Diagram:

In[15]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" requirementDiagram requirement test_req { id: 1 text: the test text. risk: high verifymethod: test } element test_entity { type: simulation } test_entity - satisfies -> test_req"]
Out[15]=

Options (3) 

Graphics

MermaidCLIOutput takes all options of Graphics. Those options are used when the second, type argument is "PDF".

MermaidDirectives (1) 

The option "MermaidDirectives" is used when the first argument is a Graph object. The value of that option is concatenated to the Mermaid graph specification prefix "graph". Here is an example:

In[16]:=
SeedRandom[1]; Block[{gr = RandomGraph[{5, 6}]}, Association[# -> ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][gr, "MermaidDirectives" -> #] & /@ {"LR", "TD"}] ]
Out[2]=

MermaidOptions (2) 

The value of the option "MermaidOptions" is given to the CLI script "mmds". Here are the CLI options:

Here is examples with using different values for the theme option:

In[17]:=
spec = "sequenceDiagram Alice->>John: Hello John, how are you? John-->>Alice: Great! Alice-)John: See you later!"; Association@Map[# -> ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][spec, "PDF", "MermaidOptions" -> "--theme " <> #] &, {"default", "forest", "dark", "neutral"}]
Out[2]=

ShellSession

This option allows the specification of shell session to be used by MermaidCLIOutput. Its values are external sessions objects (ExternalSessionObject) or "Shell".

Applications (2) 

Markdown-related conversions flowchart:

In[18]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" graph TD WL[Make a Mathematica notebook] --> E E[\"Examine notebook(s)\"] --> M2MD M2MD[\"Convert to Markdown with M2MD\"] --> MG MG[\"Convert to Mathematica with Markdown::Grammar\"] --> |Compare|E ", "PDF"]
Out[18]=

Sequence Diagram: Blogging app service communication:

In[19]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" sequenceDiagram participant web as Web Browser participant blog as Blog Service participant account as Account Service participant mail as Mail Service participant db as Storage Note over web,db: The user must be logged in to submit blog posts web->>+account: Logs in using credentials account->>db: Query stored accounts db->>account: Respond with query result alt Credentials not found account->>web: Invalid credentials else Credentials found account->>-web: Successfully logged in Note over web,db: When the user is authenticated, they can now submit new posts web->>+blog: Submit new post blog->>db: Store post data par Notifications blog--)mail: Send mail to blog subscribers blog--)db: Store in-site notifications and Response blog-->>-web: Successfully posted end end ", "PDF"] // Append[#, ImageSize -> 1000] &
Out[19]=

Properties and Relations (1) 

There is a fairly straightforward correspondence between the edge specifications for Graph and Mermaid's graph (and flowchart) specifications. Here are illustrating examples:

In[20]:=
gr = Graph[{DirectedEdge[A, B, MyTag], UndirectedEdge[A, C]}, VertexLabels -> "Name", EdgeLabels -> "EdgeTag"]
Out[20]=
In[21]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][gr, "MermaidDirectives" -> "LR"]
Out[21]=
In[22]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" graph LR A --> |MyTag|B A --- C "]
Out[22]=

Possible Issues (1) 

Make sure mermaid-cli is installed and accessible in WL. It mermaid-cli but cannot be found then set up Shell's path variable(s) in a shell session and use the option "ShellSession" to pass that session to MermaidCLIOutput. Consider using SetOptions. For example:

SetOptions[MermaidCLIOutput, "ShellSession" -> ExternalSessions[][[1]]]

Neat Examples (2) 

Larger flowchart with some styling:

In[23]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" graph TB sq[Square shape] --> ci((Circle shape)) subgraph A od>Odd shape]-- Two line<br/>edge comment --> ro di{Diamond with <br/> line break} -.-> ro(Rounded<br>square<br>shape) di==>ro2(Rounded square shape) end %% Notice that no text in shape are added here instead that is appended further down e --> od3>Really long text with linebreak<br>in an Odd shape] %% Comments after double percent signs e((Inner / circle<br>and some odd <br>special characters)) --> f(,.?!+-*ز) cyr[Cyrillic]-->cyr2((Circle shape Начало)); classDef green fill:#9f6,stroke:#333,stroke-width:2px; classDef orange fill:#f96,stroke:#333,stroke-width:4px; class sq,e green class di orange ", Automatic, "MermaidOptions" -> "--scale 3"] // ImageCrop
Out[23]=

Some interesting interaction:

In[24]:=
ResourceFunction[ CloudObject[ "https://www.wolframcloud.com/obj/antononcube/DeployedResources/Function/MermaidCLIOutput"]][" 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! "]
Out[24]=

Author Notes

In order this repository function to work mermaid-cli has to be installed. Follow the instructions at https://github.com/mermaid-js/mermaid-cli.