@docusaurus/theme-mermaid 3.8.1 → 3.9.0-canary-6406

package/lib/client/index.js

@@ -7,6 +7,7 @@
 import { useState, useEffect, useMemo } from 'react';
 import { useColorMode, useThemeConfig } from '@docusaurus/theme-common';
 import mermaid from 'mermaid';
+import { ensureLayoutsRegistered } from './layouts';
 // Stable className to allow users to easily target with CSS
 export const MermaidContainerClassName = 'docusaurus-mermaid-container';
 export function useMermaidThemeConfig() {
@@ -24,12 +25,13 @@ function useMermaidId() {
     Random client-only id, we don't care much but mermaid want an id so...
     Note: Mermaid doesn't like values provided by Rect.useId() and throws
     */
-    // TODO 2025-2026: check if useId() now works
+    // TODO Docusaurus v4: check if useId() now works
     //  It could work thanks to https://github.com/facebook/react/pull/32001
     // return useId(); // tried that, doesn't work ('#d:re:' is not a valid selector.)
     return useState(`mermaid-svg-${Math.round(Math.random() * 10000000)}`)[0];
 }
 async function renderMermaid({ id, text, config, }) {
+    await ensureLayoutsRegistered();
     /*
     Mermaid API is really weird :s
     It is a big mutable singleton with multiple config levels
@@ -48,7 +50,7 @@ async function renderMermaid({ id, text, config, }) {
     To use a new mermaid config (on colorMode change for example) we should
     update siteConfig, and it can only be done with initialize()
      */
-    mermaid.mermaidAPI.initialize(config);
+    mermaid.initialize(config);
     try {
         return await mermaid.render(id, text);
     }

package/lib/client/layouts.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+declare global {
+    const __DOCUSAURUS_MERMAID_LAYOUT_ELK_ENABLED__: boolean;
+}
+export declare function ensureLayoutsRegistered(): Promise<void>;

package/lib/client/layouts.js

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import mermaid from 'mermaid';
+async function registerOptionalElkLayout() {
+    // Mermaid does not support ELK layouts by default
+    // See https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid-layout-elk
+    // ELK layouts are heavy, so we made it an optional peer dependency
+    // See https://github.com/facebook/docusaurus/pull/11357
+    if (__DOCUSAURUS_MERMAID_LAYOUT_ELK_ENABLED__) {
+        const elkLayout = (await import('@mermaid-js/layout-elk')).default;
+        mermaid.registerLayoutLoaders(elkLayout);
+    }
+}
+// Ensure we only try to register layouts once
+let layoutsRegistered = false;
+export async function ensureLayoutsRegistered() {
+    if (!layoutsRegistered) {
+        await registerOptionalElkLayout();
+        layoutsRegistered = true;
+    }
+}

package/lib/index.d.ts

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { Plugin } from '@docusaurus/types';
-export default function themeMermaid(): Plugin<void>;
+export default function themeMermaid(): Promise<Plugin<void>>;
 export { validateThemeConfig } from './validateThemeConfig';

package/lib/index.js

@@ -8,7 +8,25 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateThemeConfig = void 0;
 exports.default = themeMermaid;
-function themeMermaid() {
+/**
+ * Check if the optional @mermaid-js/layout-elk package is available.
+ * It's an optional peer dependency because it's heavy and most Mermaid users
+ * might not need it.
+ */
+async function isElkLayoutPackageAvailable() {
+    try {
+        await import('@mermaid-js/layout-elk');
+        return true;
+    }
+    catch (e) {
+        return false;
+    }
+}
+async function themeMermaid() {
+    // For now, we infer based on package availability
+    // In the future, we could make it configurable so that users can disable it
+    // even if the package is installed?
+    const elkLayoutEnabled = await isElkLayoutPackageAvailable();
     return {
         name: 'docusaurus-theme-mermaid',
         getThemePath() {
@@ -17,6 +35,19 @@ function themeMermaid() {
         getTypeScriptThemePath() {
             return '../src/theme';
         },
+        configureWebpack(config, isServer, utils) {
+            return {
+                plugins: [
+                    new utils.currentBundler.instance.DefinePlugin({
+                        __DOCUSAURUS_MERMAID_LAYOUT_ELK_ENABLED__: JSON.stringify(
+                        // We only need to include the layout registration code on the
+                        // client side. This also solves a weird Webpack-only bug when
+                        // compiling the server config due to the module being ESM-only.
+                        !isServer && elkLayoutEnabled),
+                    }),
+                ],
+            };
+        },
     };
 }
 var validateThemeConfig_1 = require("./validateThemeConfig");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-mermaid",
-  "version": "3.8.1",
+  "version": "3.9.0-canary-6406",
   "description": "Mermaid components for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/theme-mermaid.d.ts",
@@ -33,11 +33,11 @@
     "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "dependencies": {
-    "@docusaurus/core": "3.8.1",
-    "@docusaurus/module-type-aliases": "3.8.1",
-    "@docusaurus/theme-common": "3.8.1",
-    "@docusaurus/types": "3.8.1",
-    "@docusaurus/utils-validation": "3.8.1",
+    "@docusaurus/core": "3.9.0-canary-6406",
+    "@docusaurus/module-type-aliases": "3.9.0-canary-6406",
+    "@docusaurus/theme-common": "3.9.0-canary-6406",
+    "@docusaurus/types": "3.9.0-canary-6406",
+    "@docusaurus/utils-validation": "3.9.0-canary-6406",
     "mermaid": ">=11.6.0",
     "tslib": "^2.6.0"
   },
@@ -45,11 +45,17 @@
     "react-test-renderer": "^18.0.0"
   },
   "peerDependencies": {
+    "@mermaid-js/layout-elk": "^0.1.9",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
+  "peerDependenciesMeta": {
+    "@mermaid-js/layout-elk": {
+      "optional": true
+    }
+  },
   "engines": {
-    "node": ">=18.0"
+    "node": ">=20.0"
   },
-  "gitHead": "fa8ae13e668fcbc0481ce10c0a734e2a5b397293"
+  "gitHead": "796441f4f831278ffc57971fabcd4c730da9e9d7"
 }

package/src/client/index.ts

@@ -8,6 +8,8 @@
 import {useState, useEffect, useMemo} from 'react';
 import {useColorMode, useThemeConfig} from '@docusaurus/theme-common';
 import mermaid from 'mermaid';
+import {ensureLayoutsRegistered} from './layouts';
+
 import type {RenderResult, MermaidConfig} from 'mermaid';
 import type {ThemeConfig} from '@docusaurus/theme-mermaid';
 
@@ -37,7 +39,7 @@ function useMermaidId(): string {
   Note: Mermaid doesn't like values provided by Rect.useId() and throws
   */
 
-  // TODO 2025-2026: check if useId() now works
+  // TODO Docusaurus v4: check if useId() now works
   //  It could work thanks to https://github.com/facebook/react/pull/32001
   // return useId(); // tried that, doesn't work ('#d:re:' is not a valid selector.)
 
@@ -53,6 +55,8 @@ async function renderMermaid({
   text: string;
   config: MermaidConfig;
 }): Promise<RenderResult> {
+  await ensureLayoutsRegistered();
+
   /*
   Mermaid API is really weird :s
   It is a big mutable singleton with multiple config levels
@@ -71,7 +75,7 @@ async function renderMermaid({
   To use a new mermaid config (on colorMode change for example) we should
   update siteConfig, and it can only be done with initialize()
    */
-  mermaid.mermaidAPI.initialize(config);
+  mermaid.initialize(config);
 
   try {
     return await mermaid.render(id, text);

package/src/client/layouts.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import mermaid from 'mermaid';
+
+declare global {
+  // Global variable provided by bundler DefinePlugin
+  /* eslint-disable-next-line no-underscore-dangle */
+  const __DOCUSAURUS_MERMAID_LAYOUT_ELK_ENABLED__: boolean;
+}
+
+async function registerOptionalElkLayout() {
+  // Mermaid does not support ELK layouts by default
+  // See https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid-layout-elk
+  // ELK layouts are heavy, so we made it an optional peer dependency
+  // See https://github.com/facebook/docusaurus/pull/11357
+  if (__DOCUSAURUS_MERMAID_LAYOUT_ELK_ENABLED__) {
+    const elkLayout = (await import('@mermaid-js/layout-elk')).default;
+    mermaid.registerLayoutLoaders(elkLayout);
+  }
+}
+
+// Ensure we only try to register layouts once
+let layoutsRegistered = false;
+export async function ensureLayoutsRegistered(): Promise<void> {
+  if (!layoutsRegistered) {
+    await registerOptionalElkLayout();
+    layoutsRegistered = true;
+  }
+}

package/src/index.ts

@@ -7,7 +7,26 @@
 
 import type {Plugin} from '@docusaurus/types';
 
-export default function themeMermaid(): Plugin<void> {
+/**
+ * Check if the optional @mermaid-js/layout-elk package is available.
+ * It's an optional peer dependency because it's heavy and most Mermaid users
+ * might not need it.
+ */
+async function isElkLayoutPackageAvailable() {
+  try {
+    await import('@mermaid-js/layout-elk');
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+export default async function themeMermaid(): Promise<Plugin<void>> {
+  // For now, we infer based on package availability
+  // In the future, we could make it configurable so that users can disable it
+  // even if the package is installed?
+  const elkLayoutEnabled = await isElkLayoutPackageAvailable();
+
   return {
     name: 'docusaurus-theme-mermaid',
 
@@ -17,6 +36,21 @@ export default function themeMermaid(): Plugin<void> {
     getTypeScriptThemePath() {
       return '../src/theme';
     },
+
+    configureWebpack(config, isServer, utils) {
+      return {
+        plugins: [
+          new utils.currentBundler.instance.DefinePlugin({
+            __DOCUSAURUS_MERMAID_LAYOUT_ELK_ENABLED__: JSON.stringify(
+              // We only need to include the layout registration code on the
+              // client side. This also solves a weird Webpack-only bug when
+              // compiling the server config due to the module being ESM-only.
+              !isServer && elkLayoutEnabled,
+            ),
+          }),
+        ],
+      };
+    },
   };
 }