A Mermaid subgraph puts related flowchart nodes inside a labelled boundary. It is useful when a diagram needs to show which system owns each step as well as the order of the steps. The examples below start with one group, then add connections and nested groups. Copy any complete mermaid block into a Markdown file to try it.
subgraph Service [Document service] gives the group a stable ID (Service) and a readable label. end closes the group. The node IDs Request and Render remain usable outside it, so arrows can cross the boundary. The boundary describes ownership; it does not add a processing step.
Use a short label for the group and verbs for its nodes. This makes the diagram readable even when the rendered box becomes small.
The edge from Preview to Save shows the handoff between the two groups. It is usually clearer to connect the actual steps than to draw an arrow between two large boxes: readers can see exactly what leaves one system and enters the other. Mermaid also supports edges to or from a subgraph itself, but use those when the entire group is the endpoint, not when a specific operation matters.
Here Platform contains two smaller ownership areas. Nesting is helpful when a single boundary would hide an important split, such as API versus worker. Stop nesting once the diagram needs a legend to explain the boxes; split a large architecture into an overview and a detailed diagram instead.
direction Sometimes Has No EffectYou can put direction TB or direction LR inside a subgraph to request its internal layout. There is an important limit: if a node inside that subgraph has an edge to something outside it, Mermaid may ignore the internal direction and use the parent flowchart direction. For example, the Preview --> Save edge above crosses a boundary. Choose the overall flowchart LR or flowchart TB direction first, then check the rendered result before relying on a subgraph's own direction. For the full set of direction codes, see Mermaid flowchart directions.
| Symptom | Check |
|---|---|
| The next node appears inside the box | Is there an end before that node? |
| An arrow points to the wrong place | Are you using the intended node ID rather than its displayed label? |
| The group title looks like an ID | Give it a label with subgraph ID [Readable label]. |
| Internal direction is ignored | Check for edges from contained nodes to outside nodes. |
| The diagram is too crowded | Keep an overview and move detailed internals to a second chart. |
For an exact syntax reference, see Mermaid's flowchart documentation. If a diagram fails to render after editing labels or arrows, try the Mermaid syntax error guide.
Preview these subgraph examples in mdview.io alongside the Markdown that explains them.