mirror of https://github.com/mermaid-js/mermaid.git synced 2025-09-14 12:59:46 +02:00

Files

autofix-ci[bot] 1a5a846d71 [autofix.ci] apply automated fixes

2025-06-10 15:17:07 +00:00

3.8 KiB

Raw Blame History

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:

You have Node.js installed.
You have pnpm installed globally:
```
npm install -g pnpm
```

🔄 Step-by-Step Integration

1. Clone the Mermaid Repository

git clone https://github.com/mermaid-js/mermaid.git
cd mermaid

2. Install Dependencies

Mermaid uses pnpm for dependency management:

pnpm i

3. Start the Development Server

This will spin up a local dev environment with hot reload:

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:

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:

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:

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>

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!

3.8 KiB Raw Blame History Unescape Escape

THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.

Please edit the corresponding file in /packages/mermaid/src/docs/layouts/development.md.