Mermaid

Mermaid è uno strumento straordinario per la realizzazione di diagrammi e grafici utilizzando il testo semplice.

In particolare, Mermaid.js è un linguaggio di scripting la cui sintassi in testo semplice permette di rappresentare diversi tipi di diagrammi anche molto complessi.

Il progetto Mermaid è stato creato ed è curato da Knut Sveidqvist.

Al progetto ha contribuito anche Ashish Jain.

Knut Sveidqvist e Ashish Jain hanno pubblicato la guida ufficiale di Mermaid che è il libro dal titolo “The Official Guide to Mermaid.js: Create complex diagrams and beautiful flowcharts easily using text and code”, Packt Publishing, 2021.

Nel libro citato, Knut Sveidqvist rivela il motivo del nome “Mermaid” e precisamente:

L’idea di Mermaid è nata dopo che ho provato a fare un piccolo aggiornamento di un diagramma all’interno di un documento, un compito che ha finito per richiedere una sorprendente quantità di tempo. Si è scoperto che il file di origine del diagramma non si trovava da nessuna parte, quindi il diagramma doveva essere ridisegnato da zero. Questo mi ha fatto pensare a come potevamo avere un documento completo in formato testo, con il testo del documento e le immagini nello stesso file di testo. A causa di questo, siamo arrivati a Markdown in combinazione con una nuova utility per il rendering dei diagrammi dal testo. Più tardi la stessa sera, mi sono seduto nel mio salotto per iniziare questo nuovo progetto secondario - una nuova libreria per il rendering dei grafici - mentre i miei figli guardavano La Sirenetta in TV. E da qui è nato il nome un po’ stravagante del software: Mermaid1.

Mermaid nel 2019 ha vinto il JS Open Source Award come “The Most Exciting Use of Technology” con la motivazione “Unique and unconventional use of JavaScript: a mix of original software and technologies that make the language shine and boost the development.”.

Al momento il progetto Mermaid vede coinvolti numerosi contributors.

Mermaid e Markdown

Mermaid.js può essere utilizzato con le sue integrazioni in diversi contesti ma in questa sede focalizzeremo il suo utilizzo con Markdown.

Alcuni editor Markdown, tra i quali menzioniamo Typewriter e Taio dei quali ci siamo già occupati, consentono di utilizzare le specifiche di Mermaid mediante la sua sintassi non complessa.

Il pregio del lavoro degli sviluppatori è stato di utilizzare testo semplice insieme al markup di Markdown (e di CommonMark) per semplificare la creazione di diagrammi e grafici anche complessi.

In pratica come si realizza un diagramma con Mermaid?

All’interno di un editor Markdown che - si ribadisce - supporti Mermaid è possibile scrivere delle righe di codice come nell’esempio che riportiamo di seguito:

mermaid 
pie
    title Key elements in Product X
    "Calcium" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5

All’inizio del blocco di codice va dichiarato che si tratta di uno script Mermaid mediante mermaid
Nell’esempio indicato, la seconda linea identifica un diagramma a torta mediante la dichiarazione pie, mentre le linee successive indicano i valori.

Lo script genera un iframe che, mediante Mermaid.js, viene convertito in un diagramma o grafico all’interno del browser.

Il blocco di codice su riportato, infatti, genera l’immagine seguente.


pie
    title Key elements in Product X
    "Calcium" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5

Facciamo un altro esempio.

Volendo realizzare un sequence diagram (diagramma di interazione che mostra come i processi operano tra loro e in quale ordine), utilizzeremo il seguente script:

mermaid
sequenceDiagram
    participant A as Alice
    participant J as John
    A->>J: Hello John, how are you?
    J->>A: Great!

Alice dice a John (viene indicata la direzione tra chi parla e chi ascolta con una freccia nella sintassi Mermaid è ->>da Alice verso John) “Ciao, come stai?” (Hello John, how are you?).

John risponde “Great!” (anche qui, la freccia ->> indica la direzione del messaggio da John a Alice).

Il risultato grafico sarà il seguente:

sequenceDiagram
    participant A as Alice
    participant J as John
    A->>J: Hello John, how are you?
    J->>A: Great!

Stesso discorso vale, ad esempio, per un flowchart, utilizzando il seguente codice:

mermaid
flowchart TD
    A[Start] --> B{Is it?}
    B -- Yes --> C[OK]
    C --> D[Rethink]
    D --> B
    B -- No ----> E[End]

Graficamente avremo:

flowchart TD
    A[Start] --> B{Is it?}
    B -- Yes --> C[OK]
    C --> D[Rethink]
    D --> B
    B -- No ----> E[End]

Come si può notare, sebbene abbiamo riportato degli esempi semplici, la sintassi di Mermaid non è complessa e comunque è descrivibile con testo semplice.

Indubbiamente, si possono realizzare diagrammi e grafici molto complessi a seconda delle descrizioni che saranno necessarie.

Abbiamo utilizzato Mermaid per generare dei class diagrams per il nostro progetto DAPPREMO secondo il linguaggio UML2 (Unified Modeling Language) e tra i tanti, ad esempio, abbiamo ottenuto il seguente risultato:

classDiagram
      PdP <|-- GDPR
      PdP <|-- C_Privacy
      PdP <|-- Etica
      PdP: +String legislazione
      PdP: +String Europa
      PdP: +isRegolamento(sì)
      PdP: +isDirettiva(sì)
      PdP: +isConvenzioni(sì)
      PdP: +isSoftLaw(sì)
      PdP: +int articoli
      class Etica{
          +String Filosofia
          +Norme(nessuna)
          +principi(diversi)
      }
      class GDPR{
          +String Regolamento
          +ambito_applicazione()
          +int articoli
          
      }
      class C_Privacy{
          +String D_Legislativo
          +ambito_applicazione()
          +int articoli
      }

Mermaid è certamente una risorsa molto potente che si basa sull’utilizzo del testo semplice così com’è anche per Markdown.

Qualora non si avesse a disposizione un editor Markdown che supporti Mermaid, è possibile accedere ad un editor online.

Infatti, gli sviluppatori di Mermaid hanno realizzato e reso disponibile un editor online, appunto per Mermaid, che è raggiungibile qui: https://mermaid.live.

L’editor online consente anche di poter salvare il diagramma o il grafico in formato PNG o SVG.

Mermaid, come si è detto, è un potente tool ma la curva di apprendimento non ci sembra molto ripida soprattutto se si consulta la guida online che descrive la sintassi per ciascuna tipologia di diagrammi e grafici.

In alternativa, si può approfondire Mermaid acquistando il volume citato all’inizio di questo post.

In ogni caso, al momento sono disponibili le soluzioni indicate di seguito:

Mermaid e le sue integrazioni

Ulteriore aspetto di enorme rilievo è l’integrazione di Mermaid con altri sistemi tra i quali, in particolare, va menzionato Hugo dalla versione 0.93.0.

Attualmente, come emerge da questa pagina, hanno il supporto nativo per Mermaid:

Ci sono, comunque, ulteriori numerose integrazioni di Mermaid, com’è descritto nella pagina citata per le seguenti categorie:

Sono disponibili anche delle estensioni per i browser più noti (es. Firefox).

In conclusione, Mermaid rappresenta un tool molto potente e kudos agli sviluppatori.

Buon Mermaid a tutti!

Se questa risorsa è stata utile, potreste contribuire con

Buy me a coffee

o donare via

Liberapay

Follow us on Mastodon

Stay tuned!

  1. In inglese Mermaid rappresenta la Sirena (o la Sirenetta) ovvero una creatura acquatica che per metà è donna e per altra è pesce. ↩︎

  2. Su UML, si veda anche https://www.uml-diagrams.org/ ↩︎