mirror of
https://github.com/mermaid-js/mermaid.git
synced 2025-09-08 10:06:40 +02:00
157 lines
3.5 KiB
Markdown
157 lines
3.5 KiB
Markdown
> **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
|
||
|
||
### Refer [Mermaid Contributing Guide](../community/contributing.md)
|
||
|
||
---
|
||
|
||
## 🧠 Implementing Your Custom Layout Algorithm
|
||
|
||
### 1. 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.
|
||
|
||
### 2. 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
|
||
|
||
### 3. 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>
|
||
```
|
||
|
||
### 4. 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!
|