Added documentations for implemetation of layout algorithms

2025-09-28 19:59:43 +02:00 · 2025-06-10 20:19:18 +05:30
parent 70eedd840d
commit 5e037ee315
9 changed files with 1092 additions and 0 deletions
--- a/docs/layouts/development.md
+++ b/docs/layouts/development.md
@@ -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!