🧜‍♂️ Guida a Mermaid: Diagrams as Code

::: info Cos’è Mermaid? È un linguaggio di scripting basato su JavaScript che renderizza testo in diagrammi (Flowcharts, Sequence, Gantt, ER, etc.). È supportato nativamente da Wiki.js, GitHub, GitLab e Notion. :::

1. Tool Consigliati per Sviluppo e Verifica

Per evitare l’errore che abbiamo visto (incompatibilità di versione), è fondamentale usare i tool giusti per testare i grafici prima di pubblicarli.

A. Mermaid Live Editor (Il più importante)

È il tool ufficiale online: Mermaid.live.

• Perché usarlo: Permette di vedere il grafico in tempo reale.
• Tip per la tua Wiki: Nelle impostazioni (Settings), puoi provare a vedere se il codice è compatibile con versioni precedenti, anche se solitamente punta sempre all’ultima.

B. Estensioni per VS Code

Dato che usi VS Code, queste sono obbligatorie:

1. Mermaid Editor: Permette l’anteprima live direttamente nell’IDE.
2. Markdown Preview Mermaid Support: Abilita la visualizzazione dei grafici nell’anteprima standard di VS Code (Ctrl+Shift+V).

C. Conversione in PDF/DOCX

Per esportare i tuoi documenti Markdown con grafici in formati “ufficiali”:

• Pandoc: È lo standard per convertire file. Usando il filtro mermaid-filter, puoi trasformare il codice Mermaid in immagini all’interno di PDF o Word.
• Mermaid CLI (mmdc): Un tool da riga di comando che trasforma file .mmd in immagini PNG, SVG o PDF.

2. Mini-Tutorial: Anatomia di un Grafico

Il tipo di grafico più usato è il Flowchart. Ecco le regole base:

A. Dichiarazione della direzione

Ogni grafico inizia con graph seguito dalla direzione:

• TD (Top Down): Dall’alto verso il basso.
• LR (Left to Right): Da sinistra a destra.

B. I Nodi (Le Forme)

Il testo fuori dalle parentesi è l’ID del nodo, quello dentro è l’etichetta visualizzata.

graph LR
    ID1[Rettangolo]
    ID2(Angoli Arrotondati)
    ID3{Rombo/Decisione}
    ID4((Cerchio))
    ID5[(Cilindro/Database)]

C. I Collegamenti (Frecce)

graph LR
    A --> B          -- Freccia semplice
    A --- B         -- Linea senza freccia
    A -- Testo --> B -- Freccia con testo
    A -.-> B         -- Linea tratteggiata
    A ==> B          -- Linea spessa

3. Best Practices per la compatibilità (Versione 8.8.2)

Dato che la tua Wiki usa una versione meno recente, ecco i “comandamenti” per non rompere il rendering:

1. Evita i Subgraph Nidificati: Non mettere mai un subgraph dentro un altro.
2. Usa etichette semplici: Evita caratteri speciali come parentesi o virgolette dentro i nomi dei nodi, se non strettamente necessario.
3. No direction nei Subgraph: Non usare il comando direction dentro i riquadri; usa solo la direzione globale all’inizio del file.
4. Sintassi delle Frecce: Preferisci frecce semplici -->. Le frecce bidirezionali <--> o quelle con stili complessi sono state introdotte o migliorate nelle versioni successive.

4. Esempio Pratico: Workflow di Revisione Codice

Ecco un esempio che puoi copiare nella tua Wiki per testare le tue nuove conoscenze:

graph TD
    START[Inizio Sviluppo] --> DEV[Scrittura Codice]
    DEV --> TEST{Test Locali}
    
    TEST -- Falliti --> DEV
    TEST -- Passati --> PR[Apertura Pull Request]
    
    PR --> REVIEW{Code Review}
    
    REVIEW -- Cambiamenti Richiesti --> DEV
    REVIEW -- Approvato --> MERGE[Merge nel Main]
    
    subgraph Deploy
        MERGE --> PROD[Produzione]
    end

5. Come usarlo in altri documenti (PDF, Word)

Se devi produrre un documento professionale partendo dal tuo Markdown:

1. PDF via VS Code: Usa l’estensione “Markdown PDF”. Supporta Mermaid e trasforma tutto in un PDF pulito.
2. Word (DOCX): La via più semplice è usare il Mermaid Live Editor, esportare il grafico come PNG ad alta risoluzione e incollarlo nel documento Word.
3. Automazione (Ingegnere): Se vuoi automatizzare, ti consiglio uno script Python che usa panflute (una libreria per gestire i filtri Pandoc) per intercettare i blocchi Mermaid e convertirli in immagini tramite la CLI di Mermaid prima di generare il DOCX.