To simplify a Mermaid state diagram in Obsidian on a Mac, keep every valid transition explicit, shorten labels, and test the reading direction. Compare source, destination, and transition text before accepting the result.

This walkthrough uses four synthetic states, A through D. The task is to make one diagram easier to read while preserving its direct transitions, return paths, and start and end markers. The transition table provides a concrete way to check that preservation independently of how the renderer positions the arrows.

What must stay unchanged when you simplify the diagram?

Begin by separating presentation changes from changes to the model. Shorter display labels and a different reading direction can improve readability. Removing an arrow changes the set of direct transitions, even when another route still reaches the same destination.

For example, suppose both a direct transition from A to C and a route through B exist. Deleting the direct transition would force the reader to infer an intermediate visit to B. That preserves reachability but loses a valid single-step transition. For this task, reaching the same destination eventually is insufficient.

Use the following transition inventory as the original specification. The labels are synthetic event names; they carry meaning within this example and must remain attached to their original arrows.

Source Destination Transition text
Start A None
A B step
A C alternate
B C next
B A reset
C B back
C A reset
C D finish
D End None

There are nine transitions, including start and end. Two arrows share the label reset, but they originate in different states. Keep both. Similarly, the arrows between B and C have different directions and different labels; they are separate transitions.

For a larger diagram, record each transition as a source, destination, and text combination before editing. If your original text includes conditions or actions, preserve those too. Matching the total number of arrows alone cannot detect an arrow whose destination or label has changed.

Check which renderer your installed Obsidian uses

On your Mac, open Settings using the sidebar gear, then select General. Record the current application version and installer version shown at the top. Use the application version when looking up the relevant release notes. These locations are documented in Obsidian’s Settings help.

The renderer boundary matters. Obsidian’s 1.15.0 Desktop early-access release, dated October 22, 2026, switches diagram rendering to Pele and states compatibility with Mermaid 12.1.0 syntax. Its release notes also say that this version no longer includes the Mermaid library. That statement applies to the named release; it does not identify the renderer in every installed Obsidian version. See the Obsidian 1.15.0 Desktop release notes.

Treat syntax compatibility and visual appearance as separate checks. A diagram accepted by another editor is a useful comparison, but your installed application remains the place to verify the final result. Do not assume that an upstream layout setting or a newer documentation example will behave identically in your local renderer.

The example below deliberately avoids renderer configuration, theme settings, and styling. If you already have a working diagram, begin with its existing diagram declaration and change one presentation detail at a time. An upgrade is unnecessary merely to perform the transition inventory and label edits described here.

Build a compact version with explicit transitions

The complete example below implements all nine rows of the inventory. Its visible state names are intentionally short. State A is the starting point, B and C have return paths, and only D has a transition to the end marker.

Mermaid documents state aliases, labeled transitions, start and end markers, and the direction statement in its state diagram reference. Obsidian’s documented insertion method is a fenced code block with the language identifier mermaid, as explained in Advanced formatting syntax.

```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 --> [*]
```

Paste that entire Markdown example, including its opening and closing triple-backtick lines, into a note. The outer four-backtick fence shown here only displays the example in this article; it is not part of the note content.

To inspect the exact text, use Source mode. To inspect the rendered result, switch to Reading view; on macOS, Cmd+E toggles reading and editing views. Obsidian explains these controls in Views and editing mode.

The transition statements are grouped by their source state so that each state’s outgoing options can be reviewed together. This organization helps maintain the source text; it should not be treated as a guarantee of where the renderer will place each state.

Try the example at the note width you normally use. Then remove only the direction LR line and compare the result. Keep whichever presentation makes the branching and return paths easier to follow. A left-to-right diagram can require more horizontal room, so judge the result in the actual note pane.

Shorten labels only as far as their meaning permits. In this synthetic example, Stage B needs no further explanation. In your own diagram, retain any wording that distinguishes two states. If a long explanation is necessary, put it in an adjacent prose paragraph and keep a clear mapping to the state identifier.

Which shortcuts can change the model?

Repeated arrows can tempt you to introduce a shared intermediate node. Before doing so, ask what that node represents and whether the original direct transitions still exist.

A shared reset node changes the direct paths

In the inventory, B and C each transition directly to A on reset. Replacing those arrows with paths through a new state named R creates an intermediate state and removes the original direct edges. A reader can still trace a route to A, but the diagram now describes different steps.

For the exact outcome in this article, retain the two reset arrows. Their repetition records two valid starting conditions for the same event. Reducing their visual footprint is useful only if their meaning survives.

A choice or fork needs a reason in the model

Mermaid documents <<choice>> for branching between paths and <<fork>> and <<join>> for fork and join structures. These are distinct diagram constructs in the state diagram reference.

Do not introduce one solely to gather several untidy arrows into a shared junction. In this example, the task is to retain direct state-to-state transitions. Adding an intermediate construct would require a separate explanation of how its paths correspond to the original model. Explicit arrows make that correspondence immediate.

Composite states have a documented boundary

Mermaid supports composite states, but its documentation explicitly disallows transitions between internal states belonging to different composite states. See Composite states.

If grouping your nodes produces that situation, keep the connected states flat for this task. Moving an arrow to the outer composite changes its endpoint; it is not automatically an equivalent replacement. Use a hierarchy when it represents the model’s actual structure and you can explain its entry and exit behavior.

For the four-state example, nesting adds little. The useful simplification is shorter labels and clearer presentation while leaving the transition structure intact.

Verify both the transitions and the rendered result

Use two passes before replacing the original diagram. The first checks the model; the second checks whether the chosen presentation is useful.

  1. Compare every inventory row with a transition statement. Confirm both endpoints and the full label.
  2. Compare every transition statement back to the inventory. This catches extra arrows as well as missing ones.
  3. Check start and end separately. Here, start leads only to A, and only D leads to end.
  4. Inspect the rendered diagram for readable labels and distinguishable arrowheads.
  5. Trace the return paths from B and C, since these are easy to overlook when reviewing only the forward progression.

For this example, try three reading checks: start to A, then C, then D, then end; start to A, then B, then reset to A; and start to A, then C, then back to B. These checks exercise the alternate route, reset, and reverse connection. They complement the row comparison rather than replacing it.

A deterministic text comparison confirmed that the example’s nine transition statements match the inventory, including their labels. The example was not rendered in an installed Obsidian application during preparation, so its final spacing and arrow routing still need checking in your local version.

If the note displays literal code, first confirm that you are viewing it in Reading view and that the opening fence says mermaid. If you get a parsing error after editing, return to the complete example and reapply one change at a time. If only the layout is awkward, preserve the transitions while comparing label length, direction, and available pane width.

Keep the version whose labels and paths are easiest to read after the inventory comparison passes. A successful simplification lets the reader follow the same valid transitions with less effort, while the source remains straightforward to inspect and maintain.

Sources