To connect two Mermaid subgraphs in Obsidian, give each group an explicit ID and connect those IDs. On your Mac, test a minimal diagram first, then check whether the problem is syntax, layout direction, or a difference in the installed renderer.

This guide covers visible arrows between groups in one flowchart. The task is to make the intended connection appear, identify its endpoints, and choose a practical alternative when the renderer does not produce the required arrangement.

Start with a minimal connection between two groups

Create a temporary note and paste the complete fenced block below. Obsidian’s documented method for adding a diagram is a code block whose language is mermaid; no separate diagram file is required. Advanced formatting syntax

```mermaid
flowchart LR
    subgraph groupA [Group A]
        direction TB
        A1[Item A1] --> A2[Item A2]
    end
    subgraph groupB [Group B]
        direction TB
        B1[Item B1] --> B2[Item B2]
    end
    groupA --> groupB
```

Mermaid documents explicit subgraph IDs and edges to and from subgraphs. Here, groupA and groupB identify the containers; the bracketed text supplies their titles. The final line connects the containers. Flowcharts Syntax

Switch to Reading view to inspect the result. On macOS, the documented shortcut for toggling reading and editing views is Cmd+E. You can also select Reading view through the status bar’s view control. For precise source editing, choose Source mode. Views and editing mode

Use three acceptance checks: both groups appear, their internal items appear, and an arrow connects the two group boundaries. Leave spacing and styling aside during this first check. These examples follow the retrieved syntax documentation; they have not been rendered in a local Obsidian installation for this article.

If the minimal example works, keep that note as a reference. Compare your original diagram with it in small steps: first the group declarations, then their IDs, then the single connecting line. Restore additional content only after the basic connection is visible.

Check which renderer your Obsidian version uses

Record the installed app version before comparing results with online examples. Obsidian’s update documentation places the app and installer versions under Settings → General. Select Check for updates, then Relaunch if an update is offered. Follow any separate installer notice as well. Update Obsidian

There is a significant version boundary: Obsidian’s October 22, 2026 release notes identify Desktop 1.15.0 as an early access release and say diagrams use Pele, with Mermaid 12.1.0 syntax compatibility. The same notes say Obsidian no longer includes Mermaid itself in that release. Treat instructions that assume every Obsidian installation bundles Mermaid as version-dependent. Obsidian 1.15.0 Desktop (Early access)

Those release notes also remove the Show Mermaid diagrams in notes setting in 1.15.0. If your installation displays that setting or an enablement prompt, record that difference instead of searching indefinitely for a control described for another version. Obsidian 1.15.0 Desktop (Early access)

For troubleshooting, keep a short comparison record: app version, editing or reading view, exact diagram text, and observed result. Describe the result concretely—for example, “two groups appear, but the connecting arrow is absent.” That is more useful than recording only that the diagram is broken.

Decide whether the arrow should connect groups or items

Choose the endpoints according to what the diagram needs to communicate. For a broad relationship between groups, start with the container example. For a particular transition between items, use the following complete alternative and assess it separately.

```mermaid
flowchart LR
    subgraph groupA [Group A]
        A1[Item A1] --> A2[Item A2]
    end
    subgraph groupB [Group B]
        B1[Item B1] --> B2[Item B2]
    end
    A2 --> B1
```

The last line now connects named items across the group boundary. Mermaid’s flowchart documentation distinguishes nodes, edges, and subgraphs; use the IDs of the intended endpoints consistently. Flowcharts Syntax

If the container example fails in your installed renderer but the item example works, the second is a practical fallback when an item-to-item relationship expresses your intended meaning. Preserve that distinction in the diagram: do not present a specific item transition as evidence that the containers themselves are connected.

When adapting either example, make one change at a time. First rename the visible titles, inspect the result, and then add more items. Save styling and nesting for later. This sequence gives each edit a clear purpose and makes the first change associated with a failure easier to identify.

Understand why a subgraph’s direction changes

Mermaid documents a layout limitation: when a subgraph’s node connects outside its group, the subgraph’s own direction is ignored and it inherits the parent direction. Its documentation contrasts this with a connection to the container. Direction in subgraphs

Consequently, an arrow can be correct while the arrangement differs from your intention. In the first example, inspect the internal stacks and the intergroup arrow separately. In the second, prioritize checking the item endpoints before judging the layout. Keep the renderer distinction above in mind when interpreting either result.

If you need both a specific item connection and a different internal direction, treat those as separate acceptance requirements. The documented Mermaid limitation means you should not promise that adding a local direction statement will satisfy both. Choose the connection that expresses the relationship accurately, then simplify the arrangement if necessary.

A useful fallback is to retain one overall direction and shorten the diagram until the connecting items are easy to follow. If group-level meaning is sufficient, return to the first example. These are editorial choices about what the diagram communicates, rather than guarantees about exact positions or arrow routing.

Isolate the failure before rebuilding the diagram

Use this diagnostic sequence to decide what to try next. It is a decision aid derived from the documented syntax and renderer boundaries, rather than a list of confirmed defects.

Observation Next check What to record
The note shows literal diagram text Inspect the opening and closing code fences, then switch to Reading view Whether the block renders at all
The minimal example produces an error Compare the pasted block character by character with the example The complete error text
Groups render, but their connection does not Test the complete item-to-item alternative separately Which endpoint type succeeds
The arrow appears, but internal direction changes Review the documented external-node direction limitation Whether connectivity or arrangement is the remaining issue
The example works until more content is restored Undo the latest addition and repeat that single change The smallest addition associated with failure
The same text behaves differently elsewhere Compare app versions, renderers, and view modes The exact environments and results

For an independent syntax comparison, Obsidian’s documentation recommends Mermaid’s Live Editor. Paste the diagram contents there without the surrounding Markdown fences. A successful browser rendering is useful evidence for comparison, but it does not establish identical behavior in your Obsidian version. Advanced formatting syntax

If the result still differs within Obsidian, repeat the minimal test in the desktop sandbox vault. Obsidian’s official troubleshooting guidance identifies Open Help > Sandbox Vault as the desktop check for reproducing an issue outside the normal vault setup. It also recommends updating community themes and plugins and restarting before further diagnosis. About the Bug reports category

If the sandbox succeeds, investigate differences in the original vault one at a time. If it fails too, retain the minimal example, app and installer versions, view mode, and exact observed result. Before reporting it, search the official forum for an existing matching report, as Obsidian’s reporting guidance requests. About the Bug reports category

Finish with the smallest diagram that communicates the required relationship. Keep a container connection when the groups are the intended endpoints; use an item connection when the transition belongs to particular items. Once that choice renders acceptably in your installed Obsidian version, restore additional detail gradually and stop when the diagram remains readable.

Sources