WWW::MermaidInk Raku package

The function mermaid-ink of the Raku package "WWW::MermaidInk" gets images corresponding to Mermaid-js specifications via the web Mermaid-ink interface of Mermaid-js.

For a "full set" of examples see the file MermaidInk_woven.html.

Usage

use WWW::MermaidInkloads 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 format => 'md-url')returns a string that is a Markdown image link specification.

mermaid-ink($spec format => 'svg')returns a string that is a Scalable Vector Graphics (SVG) code.

mermaid-ink($spec format => 'hash')returns a Hash object (the result of HTTP::Tiny.get.)

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 "directive" can be used to control the layout of Mermaid diagrams if the first argument is a list of pairs.

• mermaid-ink produces images or Hash objects (the result of HTTP::Tiny.get.)

Examples

Basic Examples

Generate a flowchart from a Mermaid specification:

use WWW::MermaidInk;

'graph TD 
   WL --> |ZMQ|Python --> |ZMQ|WL' 
 ==> mermaid-ink(format=>'md-url')

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-url')    

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-url')

Scalable Vector Graphics (SVG) code can be generated with format => 'svg':

mermaid-ink(@edges, format=>'svg')

Options

When format => 'svg' and subdomain => Whatever, then subdomain is automatically determined to be "svg". The argument subdomain can take the values "base64", "hash", "md-image", "md-url", "svg", Whatever.

Background color can be specified with the optional argument background.

Here is an example of using "md-url" as a format and background "Cornsilk":

'graph LR
   CompSci[Computational Science] --> Physics
   CompSci --> Math[Mathematics]
   Physics --> Philosophy 
   Math --> Philosophy'
 ==> mermaid-ink(format=>'md-url', background=>'Cornsilk') 

Command Line Interface (CLI)

The package provides the CLI script mermaid-ink. Here is its help message:

mermaid-ink --help

Flowchart

This flowchart summarizes the execution path of obtaining Mermaid images in a Markdown document:

References

Articles

[AA1] Anton Antonov, "Interactive Mermaid diagrams generation via Markdown evaluation", (2022), RakuForPrediction at WordPress.

Functions and packages

[AAf1] Anton Antonov, MermaidInk Mathematica resource function, (2022-2023), Wolfram Function Repository.

Mermaid resources

• GitHub - mermaid-js/mermaid: Generation of diagram and flowchart from text in a similar manner as markdown

• mermaid - Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams, gantt charts and git graphs.

• GitHub - mermaid-js/mermaid-cli: Command line tool for the Mermaid library

• Online FlowChart & Diagrams Editor - Mermaid Live Editor