Mermaid nei miei MDX: diagrammi architetturali che vivono nel sorgente
Ho cominciato a usare Mermaid per i diagrammi tecnici del portfolio. Il vantaggio vero non è graphical — è che il diagramma è testo, versionabile, editabile in 10 secondi, e spiega da solo cose che la prosa fatica a trasmettere.
Finché i diagrammi architetturali del mio sito sono stati screenshot di Lucidchart o draw.io, li ho aggiornati esattamente mai. Ogni modifica significava riaprire uno strumento esterno, ritoccare le box, riesportare PNG, ricaricare nell'asset. Per una persona che cambia idea spesso sull'architettura, questo lavoro si traduce in diagrammi che si staccano dalla realtà nel giro di un mese.
Ho provato Mermaid come alternativa. In pratica è una libreria JavaScript che trasforma testo in SVG: scrivi qualcosa come
e il browser lo renderizza. Non è nuova (esiste dal 2014), non è esclusiva, ma nei miei flussi MDX ha un effetto potente per tre motivi.
Primo: il diagramma vive nel sorgente del post. Quando rileggo una case study sei mesi dopo e capisco che ho bisogno di cambiare un box, apro il file MDX, ritocco due righe di testo, committo, deploy. Il PNG esterno non esiste più — niente sync da mantenere.
Secondo: il diff è leggibile. Se cambio un diagramma su git diff vedo - A --> B / + A --> C[nuovo nodo]. Con un'immagine il diff sarebbe una marea di bytes opachi. Per collaborare su un diagramma (anche solo "con me stesso sei mesi dopo") questo conta.
Terzo: stile automatico e tema-aware. Ho configurato il componente che intercetta i blocchi mermaid nei MDX per renderizzare con la palette violet/zinc del sito, e per ri-renderizzare quando cambia il tema dark/light. Non devo pensarci ogni volta — la consistenza è automatica.
Il trade-off è che Mermaid non produce diagrammi bellissimi. Se l'obiettivo è una slide da pitch con effetti grafici curati, ci sono tool migliori. Ma se l'obiettivo è documentare un'architettura tecnica in modo che resti aggiornata, vince tutto: il costo di modificare un diagramma è il costo di modificare tre righe di testo, e quando lo è, lo fai davvero.
Oggi ci sono cinque case study del portfolio con diagrammi Mermaid — ai-knowledge-base per l'architettura a quattro layer, accordi-fornitori per il ciclo business dei rebate, ticket-assistance per le identità di sicurezza, gestionale-scriptcase per il triangolo Mexal-Scriptcase-PowerApp, porting-powerapps-nodejs per il sql-proxy al centro con i suoi upstream. Ogni diagramma è sei-dodici righe di testo dentro l'MDX.
Il pattern generale che ricavo: più un asset è testo, più rimane vero nel tempo. Le architetture documentate in PNG muoiono. Quelle in testo versionato hanno una chance.