MermaidInk
MermaidInk
The function mermaid-ink
of the Raku package "WWW::MermaidInk"
gets images corresponding to a Mermaid-js specifications via the web Mermaid-ink interface of Mermaid-js.
Usage
use WWW::MermaidInk
loads the package.
mermaid-ink($spec)
retrieves an image defined by the spec $spec
from Mermaid's Ink Web interface.
mermaid-ink($spec format => 'md-image')
returns a string that is a Markdown image specification in Base64 format.
mermaid-ink($spec file => fileName)
exports the retrieved image into a specified PNG file.
mermaid-ink($spec file => Whatever)
exports the retrieved image into the file $*CMD ~ /out.png
.
Details & Options
Mermaid lets you create diagrams and visualizations using text and code.
Mermaid has different types of diagrams: Flowchart, Sequence Diagram, Class Diagram, State Diagram, Entity Relationship Diagram, User Journey, Gantt, Pie Chart, Requirement Diagram, and others. It is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.
mermaid-ink
uses the Mermaid's functionalities via the Web interface "https://mermaid.ink/img".The first argument can be a string (that is, a mermaid-js specification) or a list of pairs.
The option "directives" can be used to control the layout of Mermaid diagrams if the first argument is a list of pairs.
mermaid-ink
produces images only.
Examples
Basic Examples
Generate a flowchart from a Mermaid specification:
use WWW::MermaidInk;
'graph TD
WL --> |ZMQ|Python --> |ZMQ|WL'
==> mermaid-ink(format=>'md-image')
Create a Markdown image expression from a class diagram:
my $spec = q:to/END/;
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()
}
END
mermaid-ink($spec, format=>'md-image')
Scope
The first argument can be a list of pairs -- the corresponding Mermaid-js graph is produced. Here are the edges of directed graph:
my @edges = ['1' => '3', '3' => '1', '1' => '4', '2' => '3', '2' => '4', '3' => '4'];
Here is the corresponding mermaid-js image:
mermaid-ink(@edges, format=>'md-image')
Here is a left-to-right version:
mermaid-ink(@edges, directive => 'LR', format=>'md-image')
Create a Sequence Diagram
my $spec = q:to/END/;
sequenceDiagram
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!
END
mermaid-ink($spec, format=>'md-image')
State diagram
my $spec = q:to/END/;
stateDiagram-v2
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]
END
mermaid-ink($spec, format=>'md-image')
Entity Relationship Diagram
my $spec = q:to/END/;
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
END
mermaid-ink($spec, format=>'md-image')
User Journey
my $spec = q:to/END/;
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
END
mermaid-ink($spec, format=>'md-image')
Gantt chart
my $spec = q:to/END/;
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
END
mermaid-ink($spec, format=>'md-image')
Pie chart
my $spec = q:to/END/;
pie title Pets adopted by volunteers
"Dogs" : 386
"Cats" : 85
"Rats" : 15
END
mermaid-ink($spec, format=>'md-image')
Requirement Diagram
my $spec = q:to/END/;
requirementDiagram
requirement test_req {
id: 1
text: the test text.
risk: high
verifymethod: test
}
element test_entity {
type: simulation
}
test_entity - satisfies -> test_req
END
mermaid-ink($spec, format=>'md-image')
Options
MermaidDirectives
The option "directives" is used when the first argument is a list of pairs:
SeedRandom[1];
Block[{gr = RandomGraph[{5, 6}]},
Association[# -> my $spec = q:to/END/; gr, "MermaidDirectives" -> #] & /@ {"TB", "TD", "BT", "RL", "LR"}]
]
The meaning of Mermaid's flowchart orientation directives are given in the following table:
Applications
Create a Markdown-related conversions flowchart:
my $spec = q:to/END/;
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
END
mermaid-ink($spec, format=>'md-image')
Create a Sequence Diagram for a blogging app service communication:
my $spec = q:to/END/;
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
END
mermaid-ink($spec, format=>'md-image')
Properties and Relations
A diagram that clarifies the execution of mermaid-ink
:
my $spec = q:to/END/;
graph TD
UI[/User input/]
MS{{Mermaid-ink server}}
Raku{{Raku}}
MDnb>Markdown document]
MDIC[[Input cell]]
MDOC[[Output cell]]
MI[MermaidInk]
UI --> MDIC -.- MDnb
MDIC --> MI -.- Raku
MI --> |spec|MS
MS --> |image|MI
MI --> MDOC -.- MDnb
MDnb -.- Raku
END
mermaid-ink($spec, format=>'md-image')
For some textual content MermaidInk specifications should use quotes. Also, a new line character in text can be included using "":
my $spec = q:to/END/;
graph LR
A["Complicated text <br/>(maybe)"] --> S[Sink <br/> place]
END
mermaid-ink($spec, format=>'md-image')
Without the quotes for block "A" the specifications above does not work:
my $spec = q:to/END/;
graph LR
A[Complicated text <br/>(maybe)] --> S[Sink <br/> place]
END
mermaid-ink($spec, format=>'md-image')
Neat Examples
Larger flowchart with some styling:
my $spec = q:to/END/;
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:#9 f6,stroke:#333,stroke-width:2px;
classDef orange fill:#f96,stroke:#333,stroke-width:4px;
class sq,e green
class di orange
END
mermaid-ink($spec, format=>'md-image')
Some interesting interaction:
my $spec = q:to/END/;
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!
END
mermaid-ink($spec, format=>'md-image')