Documentation for mermaid-js#2509

docs/syntax/flowchart.md

@@ -710,42 +710,46 @@ flowchart TB
     two --> c2
 ```
 
-### Direction in subgraphs
+#### Limitation
 
-With the graphtype flowcharts you can use the direction statement to set the direction which the subgraph will render like in this example.
+Subgraph direction only takes effect if none of the subgraph nodes are linked to the outside:
 
 ```mermaid-example
 flowchart LR
-  subgraph TOP
-    direction TB
-    subgraph B1
-        direction RL
-        i1 -->f1
+    subgraph subgraph1
+        direction TB
+        top1[top] --> bottom1[bottom]
     end
-    subgraph B2
-        direction BT
-        i2 -->f2
+    subgraph subgraph2
+        direction TB
+        top2[top] --> bottom2[bottom]
     end
-  end
-  A --> TOP --> B
-  B1 --> B2
+    %% ^ These subgraphs are identical, except for the links to them:
+    
+    %% Link *to* subgraph1: subgraph1 direction is mantained
+    outside --> subgraph1
+    %% Link *within* subgraph2:
+    %% subgraph2 inherits the direction of the top-level graph (LR)
+    outside ---> top2
 ```
 
 ```mermaid
 flowchart LR
-  subgraph TOP
-    direction TB
-    subgraph B1
-        direction RL
-        i1 -->f1
+    subgraph subgraph1
+        direction TB
+        top1[top] --> bottom1[bottom]
     end
-    subgraph B2
-        direction BT
-        i2 -->f2
+    subgraph subgraph2
+        direction TB
+        top2[top] --> bottom2[bottom]
     end
-  end
-  A --> TOP --> B
-  B1 --> B2
+    %% ^ These subgraphs are identical, except for the links to them:
+    
+    %% Link *to* subgraph1: subgraph1 direction is mantained
+    outside --> subgraph1
+    %% Link *within* subgraph2:
+    %% subgraph2 inherits the direction of the top-level graph (LR)
+    outside ---> top2
 ```
 
 ## Markdown Strings

packages/mermaid/src/docs/syntax/flowchart.md

@@ -471,6 +471,29 @@ flowchart LR
   B1 --> B2
 ```
 
+#### Limitation
+
+Subgraph direction only takes effect if none of the subgraph nodes are linked to the outside:
+
+```mermaid-example
+flowchart LR
+    subgraph subgraph1
+        direction TB
+        top1[top] --> bottom1[bottom]
+    end
+    subgraph subgraph2
+        direction TB
+        top2[top] --> bottom2[bottom]
+    end
+    %% ^ These subgraphs are identical, except for the links to them:
+    
+    %% Link *to* subgraph1: subgraph1 direction is mantained
+    outside --> subgraph1
+    %% Link *within* subgraph2:
+    %% subgraph2 inherits the direction of the top-level graph (LR)
+    outside ---> top2
+```
+
 ## Markdown Strings
 
 The "Markdown Strings" feature enhances flowcharts and mind maps by offering a more versatile string type, which supports text formatting options such as bold and italics, and automatically wraps text within labels.