microsoft / microsoft/vscode

Mermaid: Subgraph disrupts node layout and edge routing vs mermaid.live

Open
#324,673 1 comment 2 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
193k
Forks
42.4k
PR merge metrics
PR metrics pending

Description

## Bug Description

When a Mermaid `graph TB` diagram uses a `subgraph`, VS Code's built-in Mermaid renderer produces a significantly different (and much less readable) layout compared to [mermaid.live](https://mermaid.live). The subgraph acts as a hard layout barrier that:

1. Pushes external nodes to the periphery instead of keeping them in the natural top-to-bottom flow
2. Breaks logical edge routing between external and internal nodes
3. Produces a diagram that is difficult to follow compared to the same code on mermaid.live

## Repro Steps

1. Create a markdown file with a Mermaid diagram that has edges between nodes outside a `subgraph` and nodes inside it (minimal repro below)
2. Open the Markdown preview

### Minimal Repro

````markdown
```mermaid
graph TB
A["External Top"]
B["External Bottom"]

subgraph Box["Container"]
direction TB
C["Internal 1"]
D["Internal 2"]
end

A --> C
C --> D
D --> B
```
````

### Full Repro (XACML architecture diagram)

Expand

````markdown
```mermaid
graph TB
classDef person fill:#08427B,stroke:#052E56,color:#fff
classDef external fill:#999999,stroke:#6B6B6B,color:#fff
classDef eiam fill:#438DD5,stroke:#2E6295,color:#fff

User["👤 User / Subject\n(person or service)"]:::person
PolicyAdmin["👤 Policy Administrator"]:::person
IdMgr["👤 Identity Manager"]:::person
SP["Service Provider\n/ Application"]:::external
PEP["PEP\n(App Middleware /\nService Mesh)"]:::external

subgraph EIAM["EIAM Platform"]
direction TB
IdP["IdP\nAuthentication\nToken Issuance\nFederation"]:::eiam
IdM["IdM\nOrg & User Lifecycle\nRole Catalogs\nDelegation"]:::eiam
PDP["PDP\nPolicy Evaluation\nPermit / Deny"]:::eiam
PRP["PRP\nPolicy Storage\n& Retrieval"]:::eiam
PAP["PAP\nPolicy Authoring\n& Administration"]:::eiam
PIP["PIP\nAttribute Provider\n(from IdM store)"]:::eiam
end

User -->|"1. Login"| SP
SP -->|"2. OIDC redirect"| IdP
IdP -->|"3. Enrich claims"| PIP
PIP -.->|"reads from"| IdM
IdP -->|"4. Token (claims)"| SP
SP -->|"5. Resource request"| PEP
PEP -->|"6. Authz request"| PDP
PDP -->|"7. Fetch policies"| PRP
PDP -->|"8. Fetch attributes"| PIP
PDP -->|"9. Decision"| PEP
PEP -->|"10. Enforce"| SP
PolicyAdmin -->|"Author policies"| PAP
PAP -->|"Store"| PRP
IdMgr -->|"Manage orgs,\nusers, roles"| IdM

style EIAM fill:#438DD510,stroke:#2E6295,stroke-width:3px,stroke-dasharray:5
```
````

## Expected Behavior (mermaid.live)

The diagram renders with a clean top-to-bottom flow. External nodes (User, SP, PEP) stay in logical flow positions, with edges crossing the subgraph boundary cleanly to reach internal nodes. The numbered sequence (1→10) is easy to follow visually.

Image

## Actual Behavior (VS Code)

The subgraph forces all internal nodes into a visual cluster, pushing external nodes (SP, PEP) to the bottom and User to the far left. The logical numbered flow (1→10) is broken and edges route awkwardly around the subgraph boundary, making the diagram difficult to read.

Image

## Environment

- VS Code: 1.127.0 (Universal)
- Commit: `4fe60c8b1cdac1c4c174f2fb180d0d758272d713`
- Date: 2026-06-30
- Electron: 42.2.0
- Chromium: 148.0.7778.97
- OS: Darwin arm64 25.5.0
- Renderer: Built-in "Mermaid Markdown Features" (introduced in VS Code 1.121)

## Additional Context

The same Mermaid code renders correctly on [mermaid.live](https://mermaid.live), producing a readable top-to-bottom flow diagram. The issue appears to be in how the built-in renderer's layout engine handles subgraph boundaries — it treats them as hard constraints that override the global `graph TB` direction, rather than as visual groupings that participate in the overall flow.

Contributor guide

Open the contributing guide

Research direction

Start in VS Code's built-in Mermaid Markdown Features by opening the minimal repro in Markdown preview, then compare its layout with mermaid.live. Done means the subgraph case preserves the expected top-to-bottom flow and readable cross-boundary edge routing; no specific source file or test is identified in the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
data-visualization, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.