Mermaid Subgraphs Laid Out Inconsistently

I'm using Mermaid to create a flowchart with subgraphs.

This works okay, except the layout works differently than I expected.

With an LR layout, the subgraphs are laid out top-down, as are the nodes inside each subgraph:

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>

<div class="mermaid">
flowchart LR

subgraph Subgraph One
  A
  -->B
  -->C
end

subgraph Subgraph Two
  D
  -->E
  -->F
end

subgraph Subgraph Three
  X
  -->Y
  -->Z
end
</div>

But if I use a TD layout, the subgraphs are laid out left-to-right, but the nodes inside each subgraph are top-down.

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>

<div class="mermaid">
flowchart TD

subgraph Subgraph One
  A
  -->B
  -->C
end

subgraph Subgraph Two
  D
  -->E
  -->F
end

subgraph Subgraph Three
  X
  -->Y
  -->Z
end
</div>

This is surprising to me: I'd expect the subgraphs to be laid out in the direction I specified (either top-down or left-right). Or at the very least, I'd expect them to be orthogonal to the layout, e.g. subgraphs being left-right with nodes that are top-down, or vice-versa.

And in both cases, the subgraphs are showing up in the opposite order I'd expect, with the last subgraph showing first.

And with more complex graphs, I'm actually seeing a mix of top-down and left-right layouts no matter which layout I specify.

How can I use Mermaid to create a graph with subgraphs that are laid out left-to-right, but whose nodes are top-down, in the order I specified them?

Solution

This is surprising to me: I'd expect the subgraphs to be laid out in the direction I specified (either top-down or left-right). Or at the very least, I'd expect them to be orthogonal to the layout, e.g. subgraphs being left-right with nodes that are top-down, or vice-versa.

I don't think that behaviour is specified, but you can explicitly specify direction in subgraphs:

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>

<div class="mermaid">
flowchart TD

subgraph Subgraph One
  direction LR  %% <-- here
  A
  -->B
  -->C
end

subgraph Subgraph Two
  direction LR  %% <-- here
  D
  -->E
  -->F
end
</div>

And in both cases, the subgraphs are showing up in the opposite order I'd expect, with the last subgraph showing first.

You could try ordering your subgraphs backwards, but I don't believe Mermaid guarantees how it will lay them out. This might render as you wish today, and change tomorrow with a new release of the software.

Mermaid's goal, at the end of the day, is to connect nodes via edges. It obeys a few hints, but if you want fully arbitrary control of layout you may wish to pick a different tool.

If you're familiar with (La)TeX, Mermaid operates similarly: it lets you focus on content by giving up fine-grained control over exactly how things are rendered. There are other tools that give you full control over layout, but that also means you have full responsibility.