Usa i sottografi dei diagrammi di flusso per i contenitori con titolo, compresi i blocchi foglia. Se i contenitori vuoti vengono visualizzati male, aggiungi uno spaziatore invisibile all’interno di ogni foglia. In questo modo si preserva la gerarchia visibile; controlla il risultato nel renderer di Obsidian installato.

Questa guida crea un diagramma neutro: un blocco esterno intitolato Collection, contenente Group A e Group B, ciascuno con contenitori foglia dotati di titolo. L’obiettivo è fare in modo che queste foglie mantengano l’aspetto di contenitori con intestazioni, invece di sostituirle con normali rettangoli con etichetta.

Cosa dovrebbe rappresentare un blocco foglia con titolo?

Rappresenta ogni contenitore visibile con un subgraph, indipendentemente dal fatto che contenga o meno un altro blocco significativo. Mermaid documenta i sottografi, gli ID espliciti dei sottografi e l’annidamento nei suoi esempi di diagrammi di flusso. Una normale dichiarazione di nodo, come leafA["Block A"], crea un nodo con etichetta; non dichiara un contenitore con titolo. Consulta Flowcharts — Basic Syntax di Mermaid.

In questo esempio, distingui il modello visibile dagli elementi di supporto del layout. Collection, i gruppi e i blocchi foglia sono gli elementi significativi. Uno spaziatore è un dettaglio implementativo che fornisce contenuto a un contenitore foglia per il layout. L’aggiunta di questo elemento ausiliario non trasforma la dichiarazione della foglia da sottografo a nodo.

Questa distinzione definisce anche i limiti di questo approccio: produce un diagramma in cui le foglie visibili restano contenitori con titolo, ma il codice sorgente include normali nodi ausiliari. Se il requisito vieta qualsiasi dichiarazione di nodo, compresi gli elementi ausiliari invisibili, questa soluzione alternativa non soddisfa tale requisito più rigido.

Controlla quale renderer usa la tua installazione su Mac

In Obsidian, apri Settings dalla barra laterale, poi seleziona General e annota la versione dell’app. La documentazione delle impostazioni di Obsidian indica General come sezione in cui trovare le informazioni sulla versione. Usa quella versione per consultare le note di rilascio pertinenti.

Esiste una differenza importante tra i renderer. Le note di rilascio ufficiali del 22 ottobre 2026 indicano che la versione Desktop 1.15.0 è in accesso anticipato e dichiarano che esegue il rendering della sintassi Mermaid tramite la libreria Pele di Obsidian, con compatibilità per la sintassi Mermaid 12.1.0. La stessa versione modifica le classi generate per i diagrammi, adottando quelle di Pele. Non dare per scontato che un’installazione meno recente usi Pele, né che la compatibilità garantisca un risultato identico a Mermaid.js. Consulta Obsidian 1.15.0 Desktop (Early access).

La documentazione Mermaid consultata per questa guida indica la versione 12.2.0. Si tratta di una versione diversa dal livello di compatibilità menzionato nelle note di rilascio di Obsidian. Considera la documentazione, un editor online e l’applicazione installata come ambienti separati finché non avrai controllato lo stesso esempio in ciascuno di essi.

Per il primo tentativo, mantieni il diagramma privo di configurazioni specifiche del renderer e di selettori di fogli di stile esterni. L’esempio seguente usa sottografi e stili locali al diagramma, offrendoti un punto di partenza essenziale per verificare la tua installazione.

Crea contenitori annidati in una nota di Obsidian

Apri una nota in modalità modifica e incolla tutto il blocco seguente, compresi i delimitatori di apertura e chiusura. Obsidian documenta i diagrammi Mermaid come blocchi di codice delimitati con l’identificatore di linguaggio mermaid. Per questo formato di nota documentato non serve alcun plugin aggiuntivo per i diagrammi. Consulta Advanced formatting syntax.

```mermaid
flowchart TB
    subgraph collection["Collection"]
        subgraph groupA["Group A"]
            subgraph blockA["Block A"]
                spacerA[" "]
            end
            subgraph blockB["Block B"]
                spacerB[" "]
            end
        end
        subgraph groupB["Group B"]
            subgraph blockC["Block C"]
                spacerC[" "]
            end
        end
    end

    classDef spacer fill:transparent,stroke:transparent,color:transparent;
    class spacerA,spacerB,spacerC spacer;
```

Premi Cmd+E per passare dalla modalità di modifica alla Reading view e viceversa. Usa la Reading view per esaminare il diagramma completato senza che il cursore di modifica mostri il codice sorgente. Questi comandi sono documentati in Views and editing mode di Obsidian.

Il risultato atteso comprende sei contenitori visibili con titolo: una raccolta, due gruppi e tre blocchi foglia. Ogni foglia contiene un elemento ausiliario la cui etichetta è un singolo spazio. La classe spacer richiede un riempimento, un bordo e un testo trasparenti. Questa soluzione combina il meccanismo delle classi documentato da Mermaid con una soluzione alternativa per il layout; Mermaid documenta classDef e l’assegnazione delle classi nella guida agli stili dei diagrammi di flusso.

L’esempio è stato verificato rispetto alla sintassi documentata, ma per questo articolo non è stato renderizzato in una sessione di Obsidian su Mac. Il criterio di accettazione è quindi visivo e locale: devono comparire tutti e sei i titoli, ciascun gruppo deve contenere le foglie assegnate e non devono essere visibili rettangoli spaziatori. La spaziatura esatta e la posizione dei blocchi allo stesso livello non sono criteri di accettazione.

Modifica le etichette senza cambiare la gerarchia

Per iniziare, modifica soltanto i titoli tra virgolette. Mantieni distinti collection, groupA, blockA e gli altri ID. In questo modo sarà più facile confrontare la versione modificata con l’esempio iniziale.

Per aggiungere un’altra foglia, copia un sottografo foglia completo, assegna ID nuovi sia al sottografo sia allo spaziatore e aggiungi il nuovo ID dello spaziatore all’assegnazione finale della classe. Inseriscilo prima di end, che chiude il gruppo contenitore. Per esempio, una quarta foglia dentro Group B va accanto a blockC, all’interno di groupB.

Leggi le istruzioni di chiusura dall’interno verso l’esterno: chiudi la foglia, poi il gruppo, infine la raccolta. L’indentazione rende visibile questa struttura durante la modifica, ma è la posizione di ogni end a determinare la correttezza del codice sorgente.

Perché usare spaziatori invece di sottografi vuoti?

Il comportamento dei contenitori vuoti è variato a seconda del renderer e della versione. Il problema Mermaid 5402 segnala che un sottografo vuoto non funziona con ELK in Mermaid 10.8.0, mentre l’esempio fornito con Dagre funziona. Si tratta di una segnalazione storica relativa a una configurazione specifica, non di una prova che ogni renderer attuale rifiuti i sottografi vuoti. Consulta Elk renderer not wokring on empty subgraph.

La conclusione pratica è di non basare interamente un diagramma destinato a un’installazione non specificata sul comportamento dei contenitori vuoti. L’approccio con gli spaziatori fornisce contenuto esplicito a ogni foglia, mantenendo il titolo significativo sul sottografo.

Usa questa guida decisionale per scegliere quanto rigorosa debba essere la struttura del codice sorgente:

Requisito Approccio iniziale Cosa controllare
Le foglie visibili devono restare contenitori con titolo Sottografi annidati con spaziatori trasparenti Titoli, contenimento ed elementi ausiliari nascosti
Il codice sorgente non deve contenere nodi ausiliari Prova sottografi foglia vuoti nel renderer di destinazione Che ogni foglia vuota venga visualizzata correttamente
I blocchi foglia conterranno in seguito elementi reali Mantieni i sottografi foglia e sostituisci gli spaziatori Rimuovi solo gli elementi ausiliari che non servono più
I blocchi richiedono una disposizione intenzionale in colonne Valuta separatamente i diagrammi a blocchi di Mermaid Supporto della sintassi installata e presentazione dei titoli

La documentazione dedicata ai diagrammi a blocchi di Mermaid descrive blocchi compositi, colonne e spaziatura esplicita. Queste funzioni meritano di essere valutate quando il compito principale è definire la disposizione. Da sole, però, non garantiscono che una conversione mantenga esattamente questa presentazione dei contenitori con titolo. Consulta Block Diagrams Documentation.

Diagnostica un risultato che non sembra corretto

Modifica una cosa alla volta. Conserva una copia dell’esempio iniziale completo in una nota separata, così potrai distinguere una differenza del renderer da un errore di modifica.

  1. La nota mostra il codice invece del diagramma. Controlla che il delimitatore di apertura usi mermaid, poi passa alla Reading view. Confronta il delimitatore con il formato dei diagrammi documentato da Obsidian.
  2. Una foglia appare come un normale rettangolo con etichetta. Controlla la dichiarazione. Dovrebbe iniziare con subgraph, con lo spaziatore su una riga separata al suo interno.
  3. All’interno di una foglia rimane visibile un piccolo rettangolo. Verifica che l’ID dello spaziatore corrisponda all’istruzione finale class. Rimuovi temporaneamente lo stile per identificare l’elemento ausiliario, poi ripristinalo.
  4. Un blocco appare nel gruppo sbagliato. Controlla la sequenza delle istruzioni di chiusura end prima di modificare le impostazioni del layout.
  5. Il diagramma funziona online ma appare diverso in Obsidian. Confronta le note di rilascio dell’app installata con la versione del renderer online. Usa come riferimento l’esempio che funziona in locale.

Preserva il contenimento prima di regolare la disposizione

Dopo aver sistemato titoli e contenimento, valuta se la disposizione è abbastanza leggibile. Non sostituire un sottografo foglia con un nodo solo per rimpicciolirne il rettangolo: questa modifica cambia la rappresentazione che intendevi preservare.

Allo stesso modo, aggiungi collegamenti solo se il diagramma deve esprimere relazioni che vanno oltre il contenimento. Mermaid documenta un limite relativo alla direzione: collegare un nodo all’interno di un sottografo con l’esterno fa sì che quel sottografo erediti la direzione del genitore. Dopo aver aggiunto questi collegamenti, ricontrolla il layout. Consulta Direction in subgraphs.

Per finire, esamina la nota alla larghezza a cui la leggi di solito. Conserva la versione in cui sono chiaramente visibili la raccolta, i gruppi e le foglie con titolo. Il risultato utile è una gerarchia di contenimento leggibile, in cui i blocchi foglia restano sottografi e gli eventuali elementi ausiliari invisibili per il layout sono ben identificati e facili da rimuovere in seguito.

Fonti