Use nested flowchart subgraphs for titled containers, including the leaf blocks. When empty containers render poorly, add an invisible spacer inside each leaf. This preserves the visible hierarchy; check the result in your installed Obsidian renderer.

This guide builds one neutral diagram: an outer block titled Collection, containing Group A and Group B, with titled leaf containers inside each group. The task is to keep those leaves looking like containers with headings, rather than replacing them with ordinary labeled rectangles.

What should represent a titled leaf block?

Represent every visible container with a subgraph, regardless of whether it contains another meaningful block. Mermaid documents subgraphs, explicit subgraph IDs, and nesting in its flowchart examples. An ordinary node declaration such as leafA["Block A"] creates a labeled node; it does not declare a titled container. See Mermaid’s Flowcharts — Basic Syntax.

For this example, distinguish the visible model from its layout support. Collection, the groups, and the leaf blocks are the meaningful elements. A spacer is an implementation detail used to give a leaf container content for layout. Adding that helper does not change the leaf’s declaration from a subgraph into a node.

That distinction also establishes the boundary of this approach: it produces a diagram whose visible leaves remain titled containers, but its source includes ordinary helper nodes. If your requirement prohibits every node declaration, including invisible helpers, this workaround does not satisfy that stricter requirement.

Check which renderer your Mac installation uses

In Obsidian, open Settings from the sidebar, then select General and note the app version. Obsidian’s Settings documentation identifies General as the location for version information. Use that version when choosing the relevant release notes.

There is a consequential renderer boundary. The official October 22, 2026 release notes label Desktop 1.15.0 as early access and say it renders Mermaid syntax through Obsidian’s Pele library, with compatibility for Mermaid 12.1.0 syntax. The same release changes the generated diagram classes to Pele’s classes. Do not assume that an older installation uses Pele, or that compatibility means identical output to Mermaid.js. See Obsidian 1.15.0 Desktop (Early access).

The Mermaid documentation retrieved for this guide displays version 12.2.0. That is a separate version from the compatibility level named in those Obsidian release notes. Treat the documentation, an online editor, and your installed application as separate environments until you have checked the same example in each.

For the first attempt, keep the diagram free of renderer-specific configuration and external stylesheet selectors. The example below uses subgraphs and diagram-local styling, giving you a small starting point for checking your own installation.

Build the nested containers in an Obsidian note

Open a note in editing view and paste the complete block below, including its opening and closing fences. Obsidian documents Mermaid diagrams as fenced code blocks with the language identifier mermaid. No additional diagram plugin is required for that documented note format. See 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;
```

Press Cmd+E to switch between editing and Reading view. Use the reading view to inspect the finished diagram without the editing cursor exposing its source. These controls are documented in Obsidian’s Views and editing mode.

The intended result has six visible titled containers: one collection, two groups, and three leaf blocks. Each leaf contains a helper whose label is a single space. The spacer class requests transparent fill, border, and text. This combines Mermaid’s documented class mechanism with a layout workaround; Mermaid documents classDef and class assignment in its flowchart styling reference.

The example has been inspected against the documented syntax; it has not been rendered in a Mac Obsidian session for this article. Its acceptance check is therefore visual and local: all six titles should appear, each group should contain its assigned leaves, and no spacer rectangle should be visible. Exact spacing and sibling positions are not acceptance criteria.

Change labels without changing the hierarchy

Start by changing only the quoted titles. Keep collection, groupA, blockA, and the other IDs distinct. This makes it easier to compare the edited version with the starting example.

To add another leaf, copy one complete leaf subgraph, give both its subgraph and spacer fresh IDs, and add the new spacer ID to the final class assignment. Place it before the enclosing group’s end. For example, a fourth leaf inside Group B belongs beside blockC, within groupB.

Read the closing statements from the inside outward: close the leaf, close its group, then close the collection. Indentation makes that structure visible while editing, but the placement of each end is what your source must express correctly.

Why use spacers instead of empty subgraphs?

Empty-container behavior has varied by renderer and version. Mermaid issue 5402 reports an empty subgraph failing with ELK in Mermaid 10.8.0, while its supplied Dagre example works. That is a historical report about a specific setup, not evidence that every current renderer rejects empty subgraphs. See Elk renderer not wokring on empty subgraph.

The practical inference is to avoid making empty-container behavior the only foundation of a diagram intended for an unspecified installation. The spacer approach gives each leaf explicit contents while keeping the meaningful title on the subgraph.

Use this decision aid when choosing how strict your source needs to be:

Requirement Starting approach What to check
Visible leaves must remain titled containers Nested subgraphs with transparent spacers Titles, containment, and hidden helpers
Source must contain no helper nodes Try empty leaf subgraphs in the target renderer Whether every empty leaf renders acceptably
Leaf blocks will later contain real items Keep the leaf subgraphs and replace their spacers Remove only the helpers that are no longer needed
Blocks need deliberate column placement Evaluate Mermaid block diagrams separately Installed syntax support and title presentation

Mermaid’s dedicated block-diagram documentation describes composite blocks, columns, and explicit spacing. Those features are worth evaluating when placement is the main task. They do not, by themselves, establish that a conversion will preserve this exact titled-container presentation. See Block Diagrams Documentation.

Diagnose a result that looks wrong

Change one thing at a time. Keep a copy of the complete starting example in a separate note so you can distinguish a renderer difference from an editing mistake.

  1. The note shows code instead of a diagram. Check that the opening fence uses mermaid, then switch to Reading view. Compare the fence with Obsidian’s documented diagram format.
  2. A leaf looks like an ordinary labeled rectangle. Inspect its declaration. It should begin with subgraph, with its spacer on a separate line inside it.
  3. A small rectangle remains visible inside a leaf. Match the spacer’s ID to the final class statement. Temporarily remove the styling to identify which helper you are seeing, then restore it.
  4. A block appears in the wrong group. Check the sequence of closing end statements before adjusting layout settings.
  5. The diagram works online but differs in Obsidian. Compare the installed app’s release notes with the online renderer’s version. Keep the working local example as your reference.

Preserve containment before adjusting placement

Once the titles and containment are correct, decide whether the arrangement is readable enough. Do not replace a leaf subgraph with a node merely to make its rectangle smaller: that edit changes the representation you set out to preserve.

Likewise, add connectors only when the diagram needs a relationship beyond containment. Mermaid documents a direction limitation: linking a node inside a subgraph to the outside causes that subgraph to inherit its parent’s direction. Recheck layout after adding such edges. See Direction in subgraphs.

Finish by inspecting the note at the width where you normally read it. Keep the version that clearly shows the collection, its groups, and their titled leaves. The useful result is a readable containment hierarchy whose leaf blocks remain subgraphs, with any invisible layout helpers explicitly understood and easy to remove later.

Sources