3.5 KiB
Warning
THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
Please edit the corresponding file in /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:
🔄 Step-by-Step Integration
Refer Mermaid Contributing Guide
🧠 Implementing Your Custom Layout Algorithm
1. Create Your Layout Folder
Navigate to the relevant source directory and create a folder for your new algorithm:
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:
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:
touch cypress/platform/myCustomLayoutTest.html
Inside the file, load your diagram like this:
<!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!