> **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
graph TD A[Node A] --> B[Node B] B --> C[Node C]
``` ### 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!