Diagrammi di ogni tipo grazie a Mermaid

Da tempo ho iniziato una personale crociata “non cruenta” per rivalutare, sostenere e promuovere l’utilizzo del plaintext come strumento di lavoro versatile e completo; ne ho parlato la prima volta nel post Plain Text Rocks e ho poi esplorato la creazione di tabelle in Tabelle e dati in testo semplice… con questo post ho deciso di inaugurare ufficialmente una sezione dedicata del blog con la tag plain!

In questo post volevo presentarti un argomento che ha sempre a che fare con il microcosmo del testo semplice, ovvero come riuscire a generare diagrammi grafici di ogni genere a partire da un set di definizioni formali puramente testuali.

Lo strumento che utilizzerò, e che ho anche integrato su questo sito, si chiama Mermaid, ed è pubblicato con licenza MIT su Github a questo indirizzo https://github.com/mermaid-js/mermaid. È un tool maturo ed eccezionale per disegnare e pubblicare diagrammi vettoriali senza utilizzare un editor come Visio, semplicemente descrivendo le entità e le relazioni che le legano con una sintassi tutt’altro che complicata.

Mermaid può essere utilizzato online con un Live-Editor, oppure lo possiamo trovare già integrato su numerose piattaforme, GitHub, GitLab, Wordpress, Google Docs, o come plugin per svariate applicazioni come ad esempio VSCode, Sublime Text e VIM. Io ho installato un plugin per consentire al mio sito, basato su Jekyll, di interpretare la sintassi di Mermaid inserita all’interno di un file markdown e generare i relativi diagrammi.

Ovviamente è possibile fare un uso ben più avanzato di questa libreria; è possibile definire funzioni di callback su eventi generati sugli elementi SVG che costituiscono i diagrammi generati e associare stili CSS specifici. Non pare che ci sia la possibilità, allo stato attuale, di animare i grafici in alcun modo, se non con tanta pazienza e olio di gomito.

Pie Chart

il Pie Chart, o diagramma a torta, è un diagramma adatto a mostrare il rapporto tra le parti e l’intero. È forse il diagramma più semplice che Mermaid è in grado di gestire. In questo caso la sintassi è molto semplice: basta inserire il titolo ed elencare le coppie chiave-valore separate da “:”. I colori sono personalizzabili utilizzando semplice CSS.

Questo è il codice necessario per la generazione:

  pie title Grafico a torta dei miei text editor preferiti
    "Notepad++": 48
    "Xed": 42
    "QOwnNotes": 33
    "VSCode": 24
    "Quillpad": 14
    "Other": 5

Flow Chart

il secondo esempio è un flow-chart, cioè un diagramma che serve a descrivere il flusso di un processo o una procedura. Questo diagramma è costituito da nodi e connessioni. In base alla forma dei nodi o delle connessioni si possono descrivere flussi condizionali, processi, input e output, come indicato dallo standard più recente pubblicato nel 1985 da ISO ISO 5807:1985.

Nel nostro esempio abbiamo utilizzato la sintassi di Mermaid seguente, che definisce i singoli nodi (con una ID, un testo e le parentesi che indicano la forma), e subito dopo realizza le connessioni (anch’esse definite con una etichetta, uno stile di freccia e uno di linea).

---
title: Esempio di FlowChart con Mermaid
---
flowchart TB
  S1(((START)))
  P11(Process1-1)
  D11{Decision1-1}
  P12(Process1-2)
  P13(Process1-3)
  P14(Process1-4)
  E1(((END)))
  S1-->P11-->D11--Condition 1-->P12-->E1
  D11--Condition 3-->P14-.->P12
  D11--Condition 2-->P13--Loop-->P11

Diagramma Gantt

Il secondo esempio è un diagramma Gantt, tipicamente utlizzato nel project management per tenere traccia delle task assegnate e del loro progresso nel tempo. Questo diagramma è costituito da una o più sezioni di attività, ciascuna descritta con un identificativo, uno stato, una data di inizio o un vincolo rispetto a una o più altre attività e da una durata o data di fine. In questo caso il codice che viene interpretato è leggermente più complicato, ma si tratta in buona sostanza di una lista.

---
title: Esempio di Diagramma di Gantt con Mermaid
---
gantt
    dateFormat  YYYY-MM-DD
    axisFormat  %Y-%m-%d
    tickInterval 1day
    title       Prova di diagramma Gantt
    excludes    weekends
    
    section A section
    Completed task           :active, des1, 2023-06-10,2023-06-11
    Future task2             :des4, after des1, 12h

    section Critical tasks
    Completed task           :crit, done, 2023-06-11,12h
    Implement feature 1      :crit, active, after des1, 6h
    Create tests             :crit, active, 18h
    Future task              :crit, 8h
    Functionality added      :milestone, 2023-06-13, 0d

    section Documentation
    Describe Feature         :active, a1, after des4, 12h
    Add another diagram      :doc1, after a1 , 6h

    section Last section
    Describe gantt syntax    :after doc1, 4h
    Push to PRD              :3h

Altri tipi di diagramma

In questo post ho esplorato i diagrammi più semplici e (per quanto mi riguarda utili), ma sono ben più numerosi quelli che è possibile generare. Questo è l’elenco completo alla data di pubblicazione:

• Flowchart
• Sequence Diagram
• Class Diagram
• State Diagram
• Entity Relationship Diagram
• User Journey
• Gantt
• Pie Chart
• Quadrant Chart
• Requirement Diagram
• Gitgraph (Git) Diagram
• C4C Diagram (Context) Diagram
• Mindmaps
• Timeline
• Zenuml

Conclusioni

Mermaid non è una libreria “perfetta”, sono molti i bug ancora aperti elencati sulla pagina di GitHub, ma è una alternativa validissima per un utilizzo leggero di queste funzionalità e soprattutto è un progetto attivo con push molto frequenti.

Per utilizzare Mermaid sul vostro PC, con un editor, si può sfruttare Visual Studio Code e l’apposito plugin, oppure, come faccio io, l’editor markdown modulare e scriptabile QOwnNotes. Non ho trovato plugin per Notepad++, purtroppo.

Per appronfondire ti lascio il link al sito ufficiale di Mermaid, dove è possibile trovare tutte le informazioni per iniziare subito ad usarla, in modo totalmente gratuito: mermaid.js.org.