Per semplificare un diagramma di stato Mermaid in Obsidian su Mac, mantieni ogni transizione valida esplicita, accorcia le etichette e verifica la direzione di lettura. Confronta sorgente, destinazione e testo della transizione prima di accettare il risultato.

Questa procedura utilizza quattro stati sintetici, da A a D. L'obiettivo è rendere un diagramma più facile da leggere preservando le sue transizioni dirette, i percorsi di ritorno e i marcatori di inizio e fine. La tabella delle transizioni fornisce un modo concreto per verificare tale preservazione indipendentemente da come il renderer posiziona le frecce.

Cosa deve restare invariato quando semplifichi il diagramma?

Inizia separando le modifiche di presentazione dalle modifiche al modello. Etichette di visualizzazione più brevi e una diversa direzione di lettura possono migliorare la leggibilità. Rimuovere una freccia cambia l'insieme delle transizioni dirette, anche quando un altro percorso raggiunge ancora la stessa destinazione.

Ad esempio, supponiamo che esista sia una transizione diretta da A a C sia un percorso attraverso B. Eliminare la transizione diretta costringerebbe il lettore a inferire una visita intermedia a B. Ciò preserva la raggiungibilità ma perde una valida transizione in un solo passo. Per questo compito, raggiungere la stessa destinazione alla fine è insufficiente.

Utilizza il seguente inventario delle transizioni come specifica originale. Le etichette sono nomi di eventi sintetici; hanno significato all'interno di questo esempio e devono rimanere attaccate alle loro frecce originali.

Sorgente Destinazione Testo transizione
Start A Nessuno
A B step
A C alternate
B C next
B A reset
C B back
C A reset
C D finish
D End Nessuno

Ci sono nove transizioni, inclusi inizio e fine. Due frecce condividono l'etichetta reset, ma originano da stati diversi. Mantienile entrambe. Analogamente, le frecce tra B e C hanno direzioni ed etichette diverse; sono transizioni separate.

Per un diagramma più grande, registra ogni transizione come combinazione di sorgente, destinazione e testo prima di modificare. Se il tuo testo originale include condizioni o azioni, preserva anche quelle. La corrispondenza del solo numero totale di frecce non può rilevare una freccia la cui destinazione o etichetta è cambiata.

Verifica quale renderer usa la tua installazione di Obsidian

Sul tuo Mac, apri Impostazioni usando l'ingranaggio nella barra laterale, poi seleziona Generale. Annota la versione dell'applicazione e la versione dell'installer mostrate in alto. Usa la versione dell'applicazione per consultare le note di rilascio pertinenti. Queste posizioni sono documentate in Guida alle Impostazioni di Obsidian.

Il confine del renderer è importante. La versione 1.15.0 Desktop early-access di Obsidian, datata 22 ottobre 2026, passa il rendering dei diagrammi a Pele e dichiara compatibilità con la sintassi Mermaid 12.1.0. Le sue note di rilascio affermano anche che questa versione non include più la libreria Mermaid. Tale affermazione si applica alla versione nominata; non identifica il renderer in ogni versione installata di Obsidian. Vedi le Note di rilascio di Obsidian 1.15.0 Desktop.

Considera la compatibilità sintattica e l'aspetto visivo come controlli separati. Un diagramma accettato da un altro editor è un utile confronto, ma la tua applicazione installata rimane il luogo per verificare il risultato finale. Non presumere che un'impostazione di layout upstream o un esempio di documentazione più recente si comporteranno identicamente nel tuo renderer locale.

L'esempio seguente evita deliberatamente la configurazione del renderer, le impostazioni del tema e lo styling. Se hai già un diagramma funzionante, inizia dalla sua dichiarazione di diagramma esistente e modifica un dettaglio di presentazione alla volta. Un aggiornamento non è necessario solo per eseguire l'inventario delle transizioni e le modifiche alle etichette descritte qui.

Costruisci una versione compatta con transizioni esplicite

L'esempio completo sotto implementa tutte e nove le righe dell'inventario. I nomi di stato visibili sono intenzionalmente brevi. Lo stato A è il punto di partenza, B e C hanno percorsi di ritorno, e solo D ha una transizione verso il marcatore di fine.

Mermaid documenta gli alias di stato, le transizioni etichettate, i marcatori di inizio e fine e l'istruzione di direzione nel suo riferimento per diagrammi di stato. Il metodo di inserimento documentato di Obsidian è un blocco di codice delimitato con l'identificatore di linguaggio mermaid, come spiegato in Sintassi di formattazione avanzata.

```mermaid
stateDiagram-v2
    direction LR

    state "Stage A" as A
    state "Stage B" as B
    state "Stage C" as C
    state "Stage D" as D

    [*] --> A

    A --> B : step
    A --> C : alternate

    B --> A : reset
    B --> C : next

    C --> A : reset
    C --> B : back
    C --> D : finish

    D --> [*]
```

Incolla l'intero esempio Markdown, incluse le righe di apertura e chiusura con triple backtick, in una nota. La recinzione esterna a quattro backtick mostrata qui serve solo a visualizzare l'esempio in questo articolo; non fa parte del contenuto della nota.

Per ispezionare il testo esatto, usa la Modalità sorgente. Per ispezionare il risultato renderizzato, passa alla Visualizzazione lettura; su macOS, Cmd+E alterna tra visualizzazione lettura e modifica. Obsidian spiega questi controlli in Visualizzazioni e modalità di modifica.

Le istruzioni di transizione sono raggruppate per stato sorgente in modo che le opzioni in uscita di ogni stato possano essere riviste insieme. Questa organizzazione aiuta a mantenere il testo sorgente; non va trattata come garanzia di dove il renderer posizionerà ogni stato.

Prova l'esempio alla larghezza di nota che usi normalmente. Poi rimuovi solo la riga direction LR e confronta il risultato. Mantieni la presentazione che rende il branching e i percorsi di ritorno più facili da seguire. Un diagramma left-to-right può richiedere più spazio orizzontale, quindi valuta il risultato nel riquadro della nota effettivo.

Accorcia le etichette solo quanto il loro significato permette. In questo esempio sintetico, Stage B non necessita ulteriore spiegazione. Nel tuo diagramma, mantieni qualsiasi wording che distingue due stati. Se una spiegazione lunga è necessaria, mettila in un paragrafo di prosa adiacente e mantieni una chiara mappatura all'identificatore di stato.

Quali scorciatoie possono cambiare il modello?

Frecce ripetute possono tentarti di introdurre un nodo intermedio condiviso. Prima di farlo, chiediti cosa rappresenta quel nodo e se le transizioni dirette originali esistono ancora.

Un nodo di reset condiviso cambia i percorsi diretti

Nell'inventario, B e C transitano ciascuno direttamente a A su reset. Sostituire quelle frecce con percorsi attraverso un nuovo stato chiamato R crea uno stato intermedio e rimuove gli edge diretti originali. Un lettore può ancora tracciare un percorso verso A, ma il diagramma ora descrive passi diversi.

Per il risultato esatto in questo articolo, mantieni le due frecce di reset. La loro ripetizione registra due condizioni di partenza valide per lo stesso evento. Ridurre la loro impronta visiva è utile solo se il loro significato sopravvive.

Una scelta o fork ha bisogno di una ragione nel modello

Mermaid documenta <<choice>> per il branching tra percorsi e <<fork>> e <<join>> per strutture fork e join. Questi sono costrutti di diagramma distinti nel riferimento per diagrammi di stato.

Non introdurli solo per raccogliere diverse frecce disordinate in un giunto condiviso. In questo esempio, il compito è mantenere le transizioni dirette stato-a-stato. Aggiungere un costrutto intermedio richiederebbe una spiegazione separata di come i suoi percorsi corrispondono al modello originale. Le frecce esplicite rendono quella corrispondenza immediata.

Gli stati composti hanno un confine documentato

Mermaid supporta gli stati composti, ma la sua documentazione vieta esplicitamente le transizioni tra stati interni appartenenti a diversi stati composti. Vedi Stati composti.

Se il raggruppamento dei tuoi nodi produce quella situazione, mantieni gli stati connessi piatti per questo compito. Spostare una freccia allo stato composto esterno cambia il suo endpoint; non è automaticamente una sostituzione equivalente. Usa una gerarchia quando rappresenta la struttura effettiva del modello e puoi spiegare il suo comportamento di ingresso e uscita.

Per l'esempio a quattro stati, l'annidamento aggiunge poco. La semplificazione utile è etichette più corte e presentazione più chiara lasciando intatta la struttura delle transizioni.

Verifica sia le transizioni che il risultato renderizzato

Usa due passaggi prima di sostituire il diagramma originale. Il primo controlla il modello; il secondo verifica se la presentazione scelta è utile.

  1. Confronta ogni riga dell'inventario con un'istruzione di transizione. Conferma entrambi gli endpoint e l'etichetta completa.
  2. Confronta ogni istruzione di transizione con l'inventario. Questo rileva frecce extra così come quelle mancanti.
  3. Controlla inizio e fine separatamente. Qui, start porta solo a A, e solo D porta a end.
  4. Ispeziona il diagramma renderizzato per etichette leggibili e punte di freccia distinguibili.
  5. Traccia i percorsi di ritorno da B e C, poiché questi sono facili da trascurare quando si rivisita solo la progressione in avanti.

Per questo esempio, prova tre controlli di lettura: start a A, poi C, poi D, poi end; start a A, poi B, poi reset a A; e start a A, poi C, poi indietro a B. Questi controlli esercitano il percorso alternativo, il reset e la connessione inversa. Completano il confronto riga per riga piuttosto che sostituirlo.

Un confronto testuale deterministico ha confermato che le nove istruzioni di transizione dell'esempio corrispondono all'inventario, incluse le loro etichette. L'esempio non è stato renderizzato in un'applicazione Obsidian installata durante la preparazione, quindi la sua spaziatura finale e il routing delle frecce necessitano ancora verifica nella tua versione locale.

Se la nota mostra codice letterale, prima conferma che la stai visualizzando in Visualizzazione lettura e che la recinzione di apertura dice mermaid. Se ottieni un errore di parsing dopo la modifica, torna all'esempio completo e riapplica una modifica alla volta. Se solo il layout è scomodo, preserva le transizioni confrontando lunghezza delle etichette, direzione e larghezza del riquadro disponibile.

Mantieni la versione le cui etichette e percorsi sono più facili da leggere dopo che il confronto dell'inventario passa. Una semplificazione riuscita permette al lettore di seguire le stesse transizioni valide con meno sforzo, mentre il sorgente rimane semplice da ispezionare e mantenere.

Fonti