marcel/mermaid
1
0
Fork 0
mirror of https://github.com/mermaid-js/mermaid.git synced 2025-08-15 06:19:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

[autofix.ci] apply automated fixes

Browse Source
This commit is contained in:
autofix-ci[bot]
2025-06-10 15:17:07 +00:00
committed by GitHub
parent 20ddc12b42
commit 1a5a846d71
4 changed files with 547 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
docs/layouts/development.md Normal file
View File

@@ -0,0 +1,177 @@
> **Warning**
>
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
>
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/layouts/development.md](../../packages/mermaid/src/docs/layouts/development.md).
# 🛠️ How to Create a New Layout Algorithm in Mermaid
Mermaid supports pluggable layout engines, and contributors can add custom layout algorithms to support specialized rendering needs such as clustered layouts, nested structures, or domain-specific visualizations.
This guide outlines the steps required to **create and integrate a new layout algorithm** into the Mermaid codebase.
---
## 📦 Prerequisites
Before starting, ensure the following:
- You have [Node.js](https://nodejs.org/) installed.
- You have [pnpm](https://pnpm.io/) installed globally:
```bash
npm install -g pnpm
```
---
## 🔄 Step-by-Step Integration
### 1. Clone the Mermaid Repository
```bash
git clone https://github.com/mermaid-js/mermaid.git
cd mermaid
```
### 2. Install Dependencies
Mermaid uses `pnpm` for dependency management:
```bash
pnpm i
```
### 3. Start the Development Server
This will spin up a local dev environment with hot reload:
```bash
pnpm dev
```
---
## 🧠 Implementing Your Custom Layout Algorithm
### 4. Create Your Layout Folder
Navigate to the relevant source directory and create a folder for your new algorithm:
```bash
cd packages/mermaid/src/layout
mkdir myCustomLayout
touch myCustomLayout/index.ts
```
> 📁 You can organize supporting files, utils, and types inside this folder.
### 5. Register the Layout Algorithm
Open the file:
```
packages/mermaid/src/rendering-util/render.ts
```
Inside the function `registerDefaultLayoutLoaders`, find the `layoutLoaders` array. Add your layout here:
```ts
registerDefaultLayoutLoaders([
...,
{
id: 'myCustomLayout',
loader: () => import('../layout/myCustomLayout'),
},
]);
```
This tells Mermaid how to load your layout dynamically by name (`id`).
---
## 🧪 Testing Your Algorithm
### 6. Create a Test File
To visually test your layout implementation, create a test HTML file in:
```
cypress/platform/
```
Example:
```bash
touch cypress/platform/myCustomLayoutTest.html
```
Inside the file, load your diagram like this:
```html
<!DOCTYPE html>
<html>
<head>
<script type="module">
import mermaid from '/dist/mermaid.esm.mjs';
mermaid.initialize({
startOnLoad: true,
theme: 'default',
layout: 'myCustomLayout', // Use your layout here
});
</script>
</head>
<body>
<div class="mermaid">graph TD A[Node A] --> B[Node B] B --> C[Node C]</div>
</body>
</html>
```
### 7. Open in Browser
After running `pnpm dev`, open your test in the browser:
```
http://localhost:9000/myCustomLayoutTest.html
```
You should see your diagram rendered using your new layout engine.
---
## 📝 Tips
- Keep your layout algorithm modular and readable.
- Use TypeScript types and helper functions for better structure.
- Add comments and constraints where necessary.
- If applicable, create a unit test and add a visual test for Cypress.
---
## 📚 Example File Structure
```
packages/
└── mermaid/
└── src/
└── layout/
└── myCustomLayout/
├── index.ts
├── utils.ts
└── types.ts
```
---
## ✅ Final Checklist
- [ ] All dependencies installed via `pnpm i`
- [ ] Layout folder and files created under `src/layout/`
- [ ] Entry registered in `registerDefaultLayoutLoaders`
- [ ] HTML test file added under `cypress/platform/`
- [ ] Diagram renders as expected at `localhost:9000`
- [ ] Code is linted and documented
---
> 💡 You’re now ready to build advanced layout algorithms and contribute to Mermaid's growing visualization capabilities!

138
docs/layouts/introduction.md Normal file
View File

@@ -0,0 +1,138 @@
> **Warning**
>
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
>
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/layouts/introduction.md](../../packages/mermaid/src/docs/layouts/introduction.md).
# 📊 Layout Algorithms in Mermaid
Mermaid is a popular JavaScript-based diagramming tool that supports auto-layout for graphs using pluggable layout engines. Layout algorithms play a critical role in rendering nodes and edges in a clean, readable, and meaningful way. Mermaid currently uses engines like **Dagre** and **ELK**, and will soon introduce a powerful new layout engine: **IPSep-CoLa**.
---
## 🔹 Dagre Layout
**Dagre** is a layout engine inspired by the **Sugiyama algorithm**, optimized for directed acyclic graphs (DAGs). It arranges nodes in layers and computes edge routing to minimize crossings and improve readability.
### Key Features:
- **Layered (Sugiyama-style) layout**: Ideal for top-down or left-to-right flow.
- **Edge routing**: Attempts to reduce edge crossings and bends.
- **Ranking**: Vertices are assigned ranks to group related elements into the same level.
- **Lightweight and fast**: Suitable for small to medium-sized graphs.
### Technical Overview:
- Works in four stages:
1. **Cycle Removal**
2. **Layer Assignment**
3. **Node Ordering**
4. **Coordinate Assignment**
- Outputs crisp layouts where edge direction is clear and logical.
### Limitations:
- No native support for **grouped or nested structures**.
- Not ideal for graphs with **non-hierarchical** or **dense cyclic connections**.
- Limited edge label placement capabilities.
---
## 🔸 ELK (Eclipse Layout Kernel)
**ELK** is a modular, extensible layout framework developed as part of the Eclipse ecosystem. It supports a wide variety of graph types and layout strategies.
### Key Features:
- **Multiple layout styles**: Hierarchical, force-based, layered, orthogonal, etc.
- **Support for ports**: Allows fine-grained edge anchoring on specific sides of nodes.
- **Group and hierarchy awareness**: Ideal for nested and compartmentalized diagrams.
- **Rich configuration**: Offers control over spacing, edge routing, direction, padding, and more.
### Technical Overview:
- Uses a **model-driven approach** with a well-defined intermediate representation (ELK Graph Model).
- Different engines are plugged in depending on the chosen layout strategy.
- Works well with large, complex, and deeply nested graphs.
### Limitations:
- Requires verbose configuration for best results.
- Can be slower than Dagre for small or simple diagrams.
- More complex to integrate and control dynamically.
---
## 🆕 IPSep-CoLa
### 🌐 Introduction
**IPSep-CoLa** stands for **Incremental Procedure for Separation Constraint Layout**, a next-generation layout algorithm tailored for **grouped, nested, and labeled graphs**. It is an enhancement over standard force-directed layouts, offering constraint enforcement and iterative refinement.
It is particularly useful for diagrams where:
- **Group integrity** is important (e.g., modules, clusters).
- **Edge labels** need smart placement.
- **Overlaps** must be prevented even under tight space constraints.
---
### ⚙️ How IPSep-CoLa Works
#### 1. **Constraint-Based Force Simulation**:
It builds on top of standard force-directed approaches (like CoLa), but adds **constraints** to influence the final positions of nodes:
- **Separation constraints**: Minimum distances between nodes, edge labels, and groups.
- **Containment constraints**: Child nodes must stay within the bounds of parent groups.
- **Alignment constraints**: Nodes can be aligned in rows or columns if desired.
#### 2. **Incremental Refinement**:
Unlike one-pass algorithms, IPSep-CoLa works in **phases**:
- Initial layout is produced using a base force simulation.
- The layout is iteratively adjusted using **constraint solvers**.
- Additional forces (spring, collision avoidance, containment) are incrementally added.
#### 3. **Edge Label Handling**:
One of the distinguishing features of IPSep-CoLa is its support for **multi-segment edge routing with mid-edge label positioning**, ensuring labels do not clutter or overlap.
---
### 📌 Use Cases
IPSep-CoLa is ideal for:
- **Hierarchical graphs** with complex nesting (e.g., software architecture, UML diagrams).
- **Clustered views** (e.g., social network groupings).
- **Diagrams with heavy labeling** where label placement affects readability.
- **Diagrams with strict visual structure** needs — maintaining boundaries, margins, or padding.
---
## 🔍 Comparison Table
| Feature | Dagre | ELK | IPSep-CoLa (Upcoming) |
| ------------------------- | ----------- | ------------------- | ------------------------------ |
| Layout Type | Layered DAG | Modular (varied) | Constraint-driven force layout |
| Edge Labeling | ⚠️ Basic | ✅ Yes | ✅ Smart Placement |
| Overlap Avoidance | ⚠️ Partial | ✅ Configurable | ✅ Automatic |
| Layout Performance | ✅ Fast | ⚠️ Medium | ⚠️ Medium |
| Customization Flexibility | ⚠️ Limited | ✅ Extensive | ✅ Moderate to High |
| Best For | Simple DAGs | Complex hierarchies | Grouped and labeled graphs |
---
## 🧾 Summary
Each layout engine in Mermaid serves a different purpose:
- **Dagre** is best for fast, simple, and readable DAGs.
- **ELK** is powerful for modular, layered, or port-based diagrams with a need for rich customization.
- **IPSep-CoLa** will soon offer a flexible, constraint-respecting layout engine that excels at **visual clarity in grouped and complex diagrams**.
The addition of IPSep-CoLa to Mermaid's layout stack represents a significant leap forward in layout control and quality — making it easier than ever to visualize rich, structured, and annotated graphs.
---

46
docs/layouts/ipsepcola/implementation.md Normal file
View File

@@ -0,0 +1,46 @@
> **Warning**
>
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
>
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/layouts/ipsepcola/implementation.md](../../../packages/mermaid/src/docs/layouts/ipsepcola/implementation.md).
## IPSEPCOLA Documentation :
IPSep-CoLa: An Incremental Procedure for Separation Constraint Layout of Graphs
## How IPSep-CoLa built :
IPSep-CoLa follows a multi-stage process to compute a well-structured layout:
1. Layer Assignment :
The layer assignment algorithm organizes nodes into hierarchical layers to create a structured layout for directed graphs. It begins by detecting and temporarily removing cyclic edges using a depth-first search (DFS) approach, ensuring the graph becomes a Directed Acyclic Graph (DAG) for proper layering. The algorithm then performs a topological sort using Kahn's method, calculating node ranks (layers) based on in-degree counts. Each node's layer is determined by its position in the topological order, with parent nodes always appearing in higher layers than their children to maintain proper flow direction.
The implementation handles special cases like nested nodes by considering parent-child relationships when calculating layers. Nodes without dependencies are placed in layer 0, while subsequent nodes are assigned to layers one level below their nearest parent. The algorithm efficiently processes nodes using a queue system, decrementing in-degrees as it progresses, and ultimately stores the layer information directly in the node objects. Though cyclic edges are removed during processing, they could potentially be reintroduced after layer assignment if needed for visualization purposes.
2. Node ordering:
After assigning layers to nodes, this step organizes nodes horizontally within each layer to minimize edge crossings and create a clean, readable layout. It uses the barycenter method—a technique that positions each node based on the average position of its connected neighbors (either incoming or outgoing). Nodes with no connections are pushed to the end of their layer.
The algorithm works in multiple passes (iterations) to refine the order: first adjusting nodes based on their incoming connections (from the layer above), then outgoing connections (to the layer below). Group nodes (like containers) are handled separately—their position is determined by averaging the positions of their children, ensuring they stay properly aligned with their contents. This approach keeps the layout structured while reducing visual clutter.
3. AssignInitial positions to node :
This step calculates the starting (x, y) positions for each node based on its assigned layer (vertical level) and order (horizontal position). Nodes are spaced evenly—horizontally using nodeSpacing and vertically using layerHeight. For example, a node in layer 2 with order 3 will be placed at (3 \_ nodeSpacing, 2 \_ layerHeight). This creates a grid-like structure where nodes align neatly in rows (layers) and columns (orders).
The initial positioning is simple but crucial—it provides a structured starting point before more advanced adjustments (like reducing edge crossings or compacting the layout) are applied. Group nodes follow the same logic, ensuring they align with their children. This method ensures a readable, organized foundation for further refinement.
4. Force-Directed Simulation with Constraints :
- Spring Forces: Attracts connected nodes to maintain desired edge lengths.
- Repulsion Forces: Pushes nodes apart to prevent overlaps.
- Group Constraints: Ensures child nodes stay near their parent groups.
- Cooling Factor: Gradually reduces movement to stabilize the layout.
5. Incremental Refinement :
- Overlap Resolution: Iteratively adjusts node positions to eliminate overlaps.
- Edge Routing: Computes smooth paths for edges, including curved paths for parallel edges and self-loops.
- Group Boundary Adjustment: Dynamically resizes group containers to fit nested elements.
6. Adjusting the Final Layout :
This step takes the calculated node positions and applies them to the visual elements of the graph. Nodes are placed at their assigned (x, y) coordinates—regular nodes are positioned directly, while group nodes (clusters) are rendered as containers that may include other nodes. Edges (connections between nodes) are drawn based on their start and end points, ensuring they follow the structured layout.
The adjustment phase bridges the mathematical layout with the actual rendering, updating the SVG or canvas elements to reflect the computed positions. This ensures that the graph is not only logically organized but also visually coherent, with proper spacing, alignment, and connections. The result is a clean, readable diagram ready for display.

186
docs/layouts/ipsepcola/overview.md Normal file
View File

@@ -0,0 +1,186 @@
> **Warning**
>
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
>
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/layouts/ipsepcola/overview.md](../../../packages/mermaid/src/docs/layouts/ipsepcola/overview.md).
## IPSEPCOLA Documentation :
IPSep-CoLa: An Incremental Procedure for Separation Constraint Layout of Graphs
## Introduction :
IPSep-CoLa (Incremental Procedure for Separation Constraint Layout) is an advanced graph layout algorithm designed to handle complex diagrams with separation constraints, such as grouped nodes, edge labels, and hierarchical structures. Unlike traditional force-directed algorithms, IPSep-CoLa incrementally refines node positions while enforcing geometric constraints to prevent overlaps, maintain group cohesion, and optimize edge routing.
The algorithm is particularly effective for visualizing nested and clustered graphs, where maintaining clear separation between elements is crucial. It combines techniques from force-directed layout, constraint satisfaction, and incremental refinement to produce readable and aesthetically pleasing diagrams.
## How IPSep-CoLa Works :
IPSep-CoLa follows a multi-stage process to compute a well-structured layout:
1. Graph Preprocessing :
Cycle Removal: Detects and temporarily removes cyclic dependencies to enable proper layering.
Layer Assignment: Assigns nodes to hierarchical layers using topological sorting.
Node Ordering: Uses the barycenter heuristic to minimize edge crossings within layers.
2. Force-Directed Simulation with Constraints :
Spring Forces: Attracts connected nodes to maintain desired edge lengths.
Repulsion Forces: Pushes nodes apart to prevent overlaps.
Group Constraints: Ensures child nodes stay near their parent groups.
Cooling Factor: Gradually reduces movement to stabilize the layout.
3. Incremental Refinement :
Overlap Resolution: Iteratively adjusts node positions to eliminate overlaps.
Edge Routing: Computes smooth paths for edges, including curved paths for parallel edges and self-loops.
Group Boundary Adjustment: Dynamically resizes group containers to fit nested elements.
## Key Features :
1. Group-Aware Layout: Maintains separation between nested structures.
2. Edge Label Placement: Uses edge labels as virtual nodes and automatically positions labels inside their parent groups.
3. Stable Convergence: Uses cooling factors and incremental updates for smooth refinement.
4. Support for Self-Loops & Parallel Edges: Avoids visual clutter with intelligent edge routing.
## Use Cases :
1. Hierarchical Diagrams (org charts, flowcharts, decision trees)
2. Network Visualization (dependency graphs, data pipelines)
3. Interactive Graph Editors (real-time layout adjustments)
4. Clustered Data Visualization (UML diagrams, biological networks)
## **Examples**
### **Example 1**
```
---
config:
layout: ipsepCola
---
flowchart TD
CEO --> MKT["Marketing Head"]
CEO --> ENG["Engineering Head"]
ENG --> DEV["Developer"]
ENG --> QA["QA Tester"]
```
### **Example 2**
```
---
config:
layout: ipsepCola
---
flowchart TD
Start["Start"] --> Red{"Is it red?"}
Red -- Yes --> Round{"Is it round?"}
Red -- No --> NotApple["❌ Not an Apple"]
Round -- Yes --> Apple["✅ It's an Apple"]
Round -- No --> NotApple2["❌ Not an Apple"]
```
### **Example 3**
```
---
config:
layout: ipsepCola
---
flowchart TD
A[Module A] --> B[Module B]
A --> C[Module C]
B --> D[Module D]
C --> D
D --> E[Module E]
```
### **Example 4**
```
---
config:
layout: ipsepCola
---
flowchart TD
Source1["📦 Raw Data (CSV)"]
Source2["🌐 API Data"]
Source1 --> Clean["🧹 Clean & Format"]
Source2 --> Clean
Clean --> Transform["🔄 Transform Data"]
Transform --> Load["📥 Load into Data Warehouse"]
Load --> BI["📊 BI Dashboard"]
```
### **Example 5**
```
---
config:
layout: ipsepCola
---
classDiagram
class Person {
-String name
-int age
+greet(): void
}
class Employee {
-int employeeId
+calculateSalary(): float
}
class Manager {
-String department
+assignTask(): void
}
Person <|-- Employee
Employee <|-- Manager
```
### **Example 6**
```
---
config:
layout: ipsepCola
---
flowchart TD
Sunlight["☀️ Sunlight"] --> Leaf["🌿 Leaf"]
Leaf --> Glucose["🍬 Glucose"]
Leaf --> Oxygen["💨 Oxygen"]
```
### **Example 7**
```
---
config:
layout: ipsepCola
---
flowchart TD
Internet["🌐 Internet"] --> Router["📡 Router"]
Router --> Server1["🖥️ Server A"]
Router --> Server2["🖥️ Server B"]
Router --> Laptop["💻 Laptop"]
%% New device joins
Router --> Mobile["📱 Mobile"]
```
## Limitations :
1. Computational Cost: More iterations may be needed for large graphs (>1000 nodes).
2. Parameter Tuning: Requires adjustments for different graph types.
3. Non-Determinism: Small variations may occur between runs due to force simulation.
## Conclusion :
IPSep-CoLa provides a robust solution for constraint-based graph layout, particularly for structured and clustered diagrams. By combining incremental refinement with separation constraints, it achieves readable and well-organized visualizations. Future improvements could include GPU acceleration and adaptive parameter tuning for large-scale graphs.