@barzhsieh/nuxt-content-mermaid 1.0.4 → 2.0.0

package/README.md

@@ -22,7 +22,7 @@ It automatically converts `mermaid` code blocks in Markdown into responsive char
 
 ## Requirements
 
-- Nuxt 3.19+ or 4.1+ (`nuxt@^3.20.1 || ^4.1.0`)
+- `nuxt@^3.20.1 || ^4.1.0`
 - `@nuxt/content@>=3.5.0`
 
 ## Quick Setup
@@ -79,20 +79,20 @@ The module will automatically transform the block into an SVG chart component.
 
 ## Configuration
 
-You can configure the module globally through the `mermaidContent` option.
+You can configure the module globally through the `contentMermaid` option.
+(`mermaidContent` is still accepted for backward compatibility, but will be removed in a future release.)
 
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
-  mermaidContent: {
+  contentMermaid: {
     enabled: true,
     loader: {
-      importSource:
-        "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs",
       init: {
         securityLevel: "strict",
         // additional options passed to mermaid.initialize()
       },
+      lazy: true,
     },
     theme: {
       useColorModeTheme: true,
@@ -115,13 +115,14 @@ export default defineNuxtConfig({
 | Option    | Type      | Default | Description                                          |
 | :-------- | :-------- | :------ | :--------------------------------------------------- |
 | `enabled` | `boolean` | `true`  | Whether the module and its conversion logic are on.  |
+| `debug`   | `boolean` | `false` | Enable verbose diagnostics; see Debug section below. |
 
 **loader**
 
-| Option                 | Type               | Default      | Description                                                            |
-| :--------------------- | :----------------- | :----------- | :--------------------------------------------------------------------- |
-| `loader.importSource`  | `string`           | jsDelivr CDN | Source to load Mermaid ESM from (supports CDN or a local path).        |
-| `loader.init`          | `MermaidConfig`    | `{ startOnLoad: false }` | Raw options object passed to `mermaid.initialize`.                     |
+| Option            | Type                                  | Default                | Description                                                                      |
+| :---------------- | :------------------------------------ | :--------------------- | :------------------------------------------------------------------------------- |
+| `loader.init`     | `MermaidConfig`                       | `{ startOnLoad: false }` | Raw options object passed to `mermaid.initialize`.                               |
+| `loader.lazy`     | `boolean \| { threshold?: number }` | `true`                 | Lazy load Mermaid when the component enters the viewport; set `false` to preload. |
 
 **theme**
 
@@ -139,10 +140,19 @@ export default defineNuxtConfig({
 | `components.spinner`      | `string` | `undefined` | Optional: global loading spinner component name.                         |
 | `components.error`        | `string` | `undefined` | Optional: global error component name when Mermaid rendering fails.      |
 
-> **Note**: All options can be overridden at runtime via `runtimeConfig.public.mermaidContent`.
+> **Note**: All options can be overridden at runtime via `runtimeConfig.public.contentMermaid` (`runtimeConfig.public.mermaidContent` remains supported but deprecated).
 
 ## Advanced Usage
 
+### Debug mode
+
+**`contentMermaid.debug`** (default `false`):
+  - **Auto-config**: If you did **not** set `loader.init.logLevel` or `suppressErrorRendering`, debug defaults them to `logLevel: 1` and `suppressErrorRendering: false` (Mermaid shows errors in the DOM). If you set them explicitly, your values win.
+  - **Runtime behavior**:
+    - **Debug on**: `mermaid.run` uses `suppressErrors: false`, errors throw with full stack traces for debugging.
+    - **Debug off**: `mermaid.run` uses `suppressErrors: true`, so one failing chart won't block others.
+  - **Console output**: Adds queue diagnostics and render-time stats.
+
 ### Theme & Color Mode
 
 The module determines the active Mermaid theme with the following priority:
@@ -154,6 +164,62 @@ The module determines the active Mermaid theme with the following priority:
    - Use `loader.init.theme` if provided.  
    - Else fall back to `theme.light`, then `theme.dark`.
 
+### Override Per-Page Settings with Frontmatter
+
+Each Markdown file can override module settings by adding a `config` field in the frontmatter.
+````markdown
+---
+title: Example of Overriding Mermaid Settings Per Page
+config:
+  theme: forest
+  flowchart:
+    htmlLabels: false
+---
+```mermaid
+flowchart LR
+  A["<b>Allow HTML labels?</b>"] --> B{Not allowed}
+```
+````
+
+> **Important: If you want to control settings via frontmatter, declare it in the collection schema in `content.config.ts`, for example:**
+>
+> ```ts
+> import { defineContentConfig, defineCollection, z } from '@nuxt/content'
+>
+> export default defineContentConfig({
+>   collections: {
+>     content: defineCollection({
+>       type: 'page',
+>       source: '**',
+>       schema: z.object({
+>         config: z.record(z.unknown()).optional(), // Declare config field
+>       }).passthrough(),
+>     }),
+>   },
+> })
+> ```
+
+### Priority Order of `%%{init}%%` Syntax, Frontmatter, and Module Settings
+
+Mermaid itself also supports overriding settings within diagrams using the `%%{init: ...}%%` syntax, for example:
+````markdown
+```mermaid
+%%{init: { 'theme': 'forest', 'flowchart': { 'curve': 'step' } }}%%
+graph TD
+  A[Input] --> B{Valid?}
+  B -- Yes --> C[Persist]
+  B -- No  --> D[Error]
+```
+````
+
+> For details, refer to the [official Mermaid documentation](https://mermaid.js.org/config/directives.html#declaring-directives)
+
+The actual priority order when settings take effect is as follows:
+
+1. **`%%{init: ...}%%` within the diagram** — Highest priority, processed directly by Mermaid.
+2. **Frontmatter `config`** — merged on top of the module's `loader.init`.
+3. **Module-level `contentMermaid.loader.init`** — Project default settings.
+
 ### Custom Rendering Component
 
 If you want full control over rendering (for example to add a border, zoom controls, or other UI), you can provide a custom component via `components.renderer`.
@@ -161,7 +227,7 @@ If you want full control over rendering (for example to add a border, zoom contr
 1. Specify the component name in `nuxt.config.ts`:
 
    ```ts
-   mermaidContent: {
+   contentMermaid: {
      components: {
        renderer: "MyCustomMermaid",
      },
@@ -193,7 +259,7 @@ Minimal example that uses the provided spinner while waiting for your own loadin
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
-  mermaidContent: {
+  contentMermaid: {
     components: {
       renderer: 'MyCustomMermaid',
       spinner: 'MySpinner', // optional: globally replace the default spinner
@@ -288,7 +354,7 @@ To reuse a global error view everywhere, register it once and reference it in co
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
-  mermaidContent: {
+  contentMermaid: {
     components: {
       error: 'MermaidError', // globally registered component name
     },

package/README.zh-TW.md

@@ -10,7 +10,7 @@
 [![Nuxt Content](https://img.shields.io/badge/Nuxt%20Content-3.x-00DC82?logo=nuxt.js)](https://content.nuxt.com/)
 
 專為 [**Nuxt Content v3**](https://content.nuxt.com/docs/getting-started) 整合 [**Mermaid**](https://mermaid.js.org/) 的模組。
-能自動將 Markdown 中的 ```mermaid 區塊轉換為響應式的圖表元件，並支援 Lazy Loading 與深色模式切換。
+能自動將 Markdown 中的 \`\`\`mermaid 區塊轉換為響應式的圖表元件，並支援 Lazy Loading 與深色模式切換。
 
 ## Features
 
@@ -22,7 +22,7 @@
 
 ## 使用前提
 
-- Nuxt 3.19 以上或 4.1 以上（`nuxt@^3.20.1 || ^4.1.0`）
+- `nuxt@^3.20.1 || ^4.1.0`
 - `@nuxt/content@>=3.5.0`
 
 ## Quick Setup
@@ -35,7 +35,7 @@
 npx nuxi module add @barzhsieh/nuxt-content-mermaid
 ```
 
-> Nuxt CLI 對第三方模組預設會裝到 `dependencies`。若想放 `devDependencies`，請裝完後移動或改用下方手動安裝。
+> Nuxt CLI 對第三方模組預設會裝到 `dependencies`。若你偏好放在 `devDependencies`，請安裝完後移動或改用下方的方式手動安裝。
 
 **裝到 `devDependencies`（需手動加入 `modules`）：**
 
@@ -79,20 +79,20 @@ graph LR
 
 ## Configuration
 
-你可以透過 `mermaidContent` 選項進行全域設定。
+你可以透過 `contentMermaid` 選項進行全域設定。  
+（`mermaidContent` 仍會被接受以維持相容，但已棄用，未來版本會移除。）
 
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
-  mermaidContent: {
+  contentMermaid: {
     enabled: true,
     loader: {
-      importSource:
-        "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs",
       init: {
         securityLevel: "strict",
         // 其他傳遞給 mermaid.initialize() 的參數
       },
+      lazy: true,
     },
     theme: {
       useColorModeTheme: true,
@@ -115,13 +115,14 @@ export default defineNuxtConfig({
 | 參數      | 類型      | 預設值 | 說明                           |
 | :-------- | :-------- | :----- | :----------------------------- |
 | `enabled` | `boolean` | `true` | 是否啟用模組與轉換邏輯。       |
+| `debug`   | `boolean` | `false` | 啟用除錯模式；見下方 Debug 說明。 |
 
 **loader**
 
-| 參數                  | 類型            | 預設值                  | 說明                                                       |
-| :-------------------- | :-------------- | :---------------------- | :--------------------------------------------------------- |
-| `loader.importSource` | `string`        | jsDelivr CDN            | 指定 Mermaid ESM 的載入來源（支援 CDN 或本地路徑）。       |
-| `loader.init`         | `MermaidConfig` | `{ startOnLoad: false }` | 直接傳遞給 `mermaid.initialize` 的原始設定。               |
+| 參數             | 類型                                   | 預設值                   | 說明                                                                  |
+| :--------------- | :------------------------------------- | :----------------------- | :---------------------------------------------------------------------- |
+| `loader.init`    | `MermaidConfig`                        | `{ startOnLoad: false }` | 直接傳遞給 `mermaid.initialize` 的原始設定。                            |
+| `loader.lazy`    | `boolean \| { threshold?: number }` | `true`                  | 元件進入 viewport 時才載入 Mermaid；設為 `false` 會在前一刻就載入。 |
 
 **theme**
 
@@ -139,10 +140,19 @@ export default defineNuxtConfig({
 | `components.spinner`     | `string` | `undefined` | 指定全域的 Loading 元件名稱。                          |
 | `components.error`       | `string` | `undefined` | 指定全域的錯誤顯示元件名稱，渲染失敗時會使用。         |
 
-> **Note**: 所有設定皆可透過 `runtimeConfig.public.mermaidContent` 在部署時進行覆寫。
+> **Note**: 所有設定皆可透過 `runtimeConfig.public.contentMermaid` 在部署時進行覆寫（`runtimeConfig.public.mermaidContent` 仍支援但已棄用）。
 
 ## Advanced Usage
 
+### Debug 模式
+
+**`contentMermaid.debug`**（預設 `false`）：
+  - **自動配置**：若未手動設定 `loader.init.logLevel` 或 `suppressErrorRendering`，開啟 debug 模式會自動將 `logLevel` 設為 `1` (Info)，並將 `suppressErrorRendering` 設為 `false`（允許 Mermaid 在 DOM 中顯示錯誤訊息）。
+  - **執行行為**：
+    - **Debug 開啟**：`mermaid.run` 使用 `suppressErrors: false`，發生錯誤時會拋出完整堆疊以便除錯。
+    - **Debug 關閉**：`mermaid.run` 使用 `suppressErrors: true`，避免單一圖表錯誤中斷其他圖表的渲染。
+  - **主控台輸出**：模組會額外輸出渲染佇列的診斷資訊與執行時間統計。
+
 ### 主題與顏色模式 (Color Mode)
 
 模組會依據以下優先順序決定主題：
@@ -154,6 +164,65 @@ export default defineNuxtConfig({
    - 優先使用 `loader.init.theme`。  
    - 若未提供，依序回退至 `theme.light`，若沒有設置則會回退至 `theme.dark`。
 
+### 以 frontmatter 覆寫單頁設定
+
+每篇 Markdown 都可以透過於 frontmatter 中加入 `config` 欄位來覆寫模組設定。
+
+````markdown
+---
+title: 單篇覆寫 Mermaid 設定範例
+config:
+  theme: forest
+  flowchart:
+    htmlLabels: false
+---
+
+```mermaid
+flowchart LR
+  A["<b>允許 HTML labels？</b>"] --> B{不允許}
+```
+````
+
+> **重要：如果要使用 frontmatter 控制設定，請在 `content.config.ts` 的 collection schema 中宣告它，例如：**
+>
+> ```ts
+> import { defineContentConfig, defineCollection, z } from '@nuxt/content'
+>
+> export default defineContentConfig({
+>   collections: {
+>     content: defineCollection({
+>       type: 'page',
+>       source: '**',
+>       schema: z.object({
+>         config: z.record(z.unknown()).optional(), // 宣告 config 欄位
+>       }).passthrough(),
+>     }),
+>   },
+> })
+> ```
+
+### `%%{init}%%` 語法、frontmatter 與模組設定的優先順序
+
+Mermaid 本身也支援在圖表內透過 `%%{init: ...}%%` 語法覆寫設定，例如：
+
+````markdown
+```mermaid
+%%{init: { 'theme': 'forest', 'flowchart': { 'curve': 'step' } }}%%
+graph TD
+  A[Input] --> B{Valid?}
+  B -- Yes --> C[Persist]
+  B -- No  --> D[Error]
+```
+````
+
+> 細節可參考 [Mermaid 官方文件](https://mermaid.js.org/config/directives.html#declaring-directives)
+
+實際生效時的優先順序如下：
+
+1. **圖表內的 `%%{init: ...}%%`** —— 最優先，直接由 Mermaid 處理。  
+2. **frontmatter `config`** —— 深度合併在模組的 `loader.init` 之上。  
+3. **模組層級的 `contentMermaid.loader.init`** —— 專案的全域預設。  
+
 ### 自訂渲染元件 (Custom Component)
 
 若需完全接管 Mermaid 的渲染行為（例如：加入外框、ZoomIn/Out 功能），可指定 `components.renderer`。
@@ -161,7 +230,7 @@ export default defineNuxtConfig({
 1. 在 `nuxt.config.ts` 中指定元件名稱：
 
    ```ts
-   mermaidContent: {
+   contentMermaid: {
      components: {
        renderer: "MyCustomMermaid",
      }
@@ -193,7 +262,7 @@ export default defineNuxtConfig({
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
-  mermaidContent: {
+  contentMermaid: {
     components: {
       renderer: 'MyCustomMermaid',
       spinner: 'MySpinner', // 選填：改用自己的全域 Loading 元件
@@ -287,7 +356,7 @@ onMounted(() => { loading.value = false })
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
-  mermaidContent: {
+  contentMermaid: {
     components: {
       error: 'MermaidError', // 全域註冊的元件名稱
     },

package/dist/module.d.mts

@@ -7,14 +7,15 @@ interface ModuleOptions {
      * @default true
      */
     enabled?: boolean;
+    /**
+     * Enable debug mode for detailed logging and error reporting
+     * @default false
+     */
+    debug?: boolean;
     /**
      * Options related to loading mermaid
      */
     loader?: {
-        /**
-         * Mermaid ESM source, can be a CDN URL or local /public path
-         */
-        importSource?: string;
         /**
          * Pass-through to `mermaid.initialize`
          */
@@ -66,5 +67,7 @@ interface ModuleOptions {
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
-export { _default as default };
+declare function transformMermaidCodeBlocks(body: string, componentName: string, frontmatterConfigKey?: string): string;
+
+export { _default as default, transformMermaidCodeBlocks };
 export type { ModuleOptions };

package/dist/module.json

@@ -1,10 +1,10 @@
 {
   "name": "@barzhsieh/nuxt-content-mermaid",
-  "configKey": "mermaidContent",
+  "configKey": "contentMermaid",
   "compatibility": {
     "nuxt": "^3.20.1 || ^4.1.0"
   },
-  "version": "1.0.4",
+  "version": "2.0.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,13 +1,12 @@
-import { defineNuxtModule, createResolver, addPlugin, addComponent, addTypeTemplate } from '@nuxt/kit';
+import { defineNuxtModule, useLogger, createResolver, addPlugin, addComponent, addTypeTemplate } from '@nuxt/kit';
 import { defu } from 'defu';
-import { DEFAULT_MERMAID_INIT, DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, DEFAULT_IMPORT_SOURCE } from '../dist/runtime/constants.js';
+import { DEFAULT_MERMAID_CONFIG, DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, DEFAULT_FRONTMATTER_CONFIG_KEY } from '../dist/runtime/constants.js';
 
 const MERMAID_BLOCK = /```mermaid([\s\S]*?)```/gi;
 const DEFAULTS = {
   enabled: true,
   loader: {
-    importSource: DEFAULT_IMPORT_SOURCE,
-    init: { ...DEFAULT_MERMAID_INIT },
+    init: { ...DEFAULT_MERMAID_CONFIG },
     lazy: true
   },
   theme: {
@@ -24,7 +23,7 @@ const DEFAULTS = {
 const module$1 = defineNuxtModule({
   meta: {
     name: "@barzhsieh/nuxt-content-mermaid",
-    configKey: "mermaidContent",
+    configKey: "contentMermaid",
     compatibility: {
       nuxt: "^3.20.1 || ^4.1.0"
     }
@@ -33,15 +32,30 @@ const module$1 = defineNuxtModule({
     ...DEFAULTS
   },
   setup(options, nuxt) {
-    const resolvedOptions = defu(options, DEFAULTS);
+    const logger = useLogger("nuxt-content-mermaid");
+    const warn = (message) => logger.warn(message);
+    const deprecatedOptions = nuxt.options.mermaidContent;
+    const hasDeprecatedOptions = deprecatedOptions && typeof deprecatedOptions === "object" && Object.keys(deprecatedOptions).length > 0;
+    if (hasDeprecatedOptions)
+      warn("[nuxt-content-mermaid] `mermaidContent` is deprecated, please switch to `contentMermaid`. The old key is still read for now but will be removed in a future release.");
+    const resolvedOptions = defu(
+      {},
+      options,
+      deprecatedOptions,
+      DEFAULTS
+    );
     const resolver = createResolver(import.meta.url);
     const runtimeDir = resolver.resolve("./runtime");
     const publicRuntimeConfig = nuxt.options.runtimeConfig.public;
-    const runtimeOverrides = publicRuntimeConfig.mermaidContent || {};
+    const runtimeOverrides = publicRuntimeConfig.contentMermaid || publicRuntimeConfig.mermaidContent || {};
+    if (!publicRuntimeConfig.contentMermaid && publicRuntimeConfig.mermaidContent)
+      warn("[nuxt-content-mermaid] `runtimeConfig.public.mermaidContent` is deprecated, please use `runtimeConfig.public.contentMermaid` instead.");
     const runtimeMermaidConfig = defu(
+      {},
       runtimeOverrides,
       resolvedOptions
     );
+    publicRuntimeConfig.contentMermaid = runtimeMermaidConfig;
     publicRuntimeConfig.mermaidContent = runtimeMermaidConfig;
     const baseMermaidComponentName = "Mermaid";
     const isEnabled = runtimeMermaidConfig.enabled !== false;
@@ -83,19 +97,13 @@ export {}
     });
   }
 });
-function escapeHtml(text) {
-  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
-}
-function transformMermaidCodeBlocks(body, componentName) {
+function transformMermaidCodeBlocks(body, componentName, frontmatterConfigKey = DEFAULT_FRONTMATTER_CONFIG_KEY) {
   return body.replace(MERMAID_BLOCK, (_, rawCode = "") => {
     const code = rawCode.trim();
     if (!code) return _;
-    const escaped = escapeHtml(code);
-    return `<${componentName}>
-<pre><code>${escaped}
-</code></pre>
-</${componentName}>`;
+    const encoded = encodeURIComponent(code);
+    return `<${componentName} :config="${frontmatterConfigKey}" code="${encoded}"></${componentName}>`;
   });
 }
 
-export { module$1 as default };
+export { module$1 as default, transformMermaidCodeBlocks };

package/dist/runtime/components/Mermaid.d.vue.ts

@@ -1,3 +1,8 @@
+import type { MermaidConfig } from 'mermaid';
+type __VLS_Props = {
+    config?: MermaidConfig | string | unknown;
+    code?: string;
+};
 declare var __VLS_1: {}, __VLS_9: {}, __VLS_11: {}, __VLS_13: {}, __VLS_21: {
     error: unknown;
     source: string;
@@ -13,7 +18,7 @@ type __VLS_Slots = {} & {
 } & {
     error?: (props: typeof __VLS_21) => any;
 };
-declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/runtime/components/Mermaid.vue

@@ -10,15 +10,21 @@ import {
   shallowRef,
   useTemplateRef
 } from "vue";
+import { mergeMermaidConfig, resolveMermaidTheme } from "../mermaid-config";
 import { enqueueRender } from "../utils";
 import Spinner from "./Spinner.vue";
+const props = defineProps({
+  config: { type: null, required: false },
+  code: { type: String, required: false }
+});
 const nuxtApp = useNuxtApp();
 const runtimeConfig = useRuntimeConfig();
-const mermaidContent = runtimeConfig.public?.mermaidContent || {};
-const isEnabled = mermaidContent.enabled !== false;
-const loaderOptions = mermaidContent.loader || {};
-const themeOptions = mermaidContent.theme || {};
-const componentOptions = mermaidContent.components || {};
+const contentMermaidOptions = runtimeConfig.public?.contentMermaid || runtimeConfig.public?.mermaidContent || {};
+const isEnabled = contentMermaidOptions.enabled !== false;
+const debug = contentMermaidOptions.debug || false;
+const loaderOptions = contentMermaidOptions.loader || {};
+const themeOptions = contentMermaidOptions.theme || {};
+const componentOptions = contentMermaidOptions.components || {};
 const lazyOption = loaderOptions.lazy;
 const isLazy = lazyOption !== false;
 const lazyThreshold = typeof lazyOption === "object" && typeof lazyOption.threshold === "number" ? lazyOption.threshold : 0.1;
@@ -33,12 +39,40 @@ const hasRenderedOnce = ref(false);
 const isLoading = ref(false);
 const hasError = ref(false);
 const errorContent = shallowRef(null);
-let mermaidDefinition = "";
+const decodedCode = computed(() => props.code ? decodeURIComponent(props.code) : "");
+const mermaidDefinition = ref(decodedCode.value);
 let observer = null;
+const frontmatterConfig = computed(() => {
+  const value = props.config;
+  if (!value)
+    return void 0;
+  if (typeof value !== "object") {
+    if (import.meta.dev) {
+      console.warn(
+        "[nuxt-content-mermaid] Ignoring non-object `config` prop on <Mermaid> component. This usually means your `content.config.ts` collection schema did not declare `config` as a JSON field. See README section about per-page overrides via frontmatter.",
+        value
+      );
+    }
+    return void 0;
+  }
+  return value;
+});
 const mermaidTheme = computed(() => {
-  if (useColorModeTheme && colorMode)
-    return colorMode.value === "dark" ? darkTheme : lightTheme;
-  return baseMermaidInit.theme ?? lightTheme ?? darkTheme;
+  return resolveMermaidTheme({
+    useColorModeTheme,
+    colorModeValue: colorMode?.value,
+    frontmatterTheme: frontmatterConfig.value?.theme,
+    baseTheme: baseMermaidInit.theme,
+    lightTheme,
+    darkTheme
+  });
+});
+const effectiveMermaidInit = computed(() => {
+  return mergeMermaidConfig({
+    baseConfig: baseMermaidInit,
+    overrideConfig: frontmatterConfig.value,
+    theme: mermaidTheme.value
+  });
 });
 const configuredSpinnerName = computed(() => componentOptions.spinner?.trim() || "");
 const customSpinner = shallowRef(null);
@@ -108,46 +142,78 @@ function serializeMermaidFromNode(root) {
   if (root.nodeType === ELEMENT_NODE) {
     const el = root;
     const tag = el.tagName?.toUpperCase();
-    if (tag === "BR") return "<br/>";
+    if (tag === "BR") return "\n";
+    const blockTags = [
+      "DIV",
+      "P",
+      "LI",
+      "TR",
+      "H1",
+      "H2",
+      "H3",
+      "H4",
+      "H5",
+      "H6",
+      "BLOCKQUOTE",
+      "PRE",
+      "UL",
+      "OL",
+      "DL",
+      "DT",
+      "DD",
+      "TABLE",
+      "THEAD",
+      "TBODY",
+      "TFOOT",
+      "SECTION",
+      "ARTICLE",
+      "ASIDE",
+      "HEADER",
+      "FOOTER",
+      "MAIN"
+    ];
+    const isBlock = blockTags.includes(tag) || el.classList.contains("line") || el.classList.contains("code-line");
     let out = "";
     el.childNodes.forEach((child) => {
       out += serializeMermaidFromNode(child);
     });
+    if (isBlock) return "\n" + out + "\n";
     return out;
   }
   return "";
 }
 function extractMermaidDefinition(container) {
+  const codeNodes = Array.from(container.querySelectorAll("code"));
+  if (codeNodes.length > 0) {
+    return codeNodes.map((node) => serializeMermaidFromNode(node)).join("\n").trim();
+  }
   const pre = container.querySelector("pre");
-  const code = container.querySelector("code");
-  if (code) return code.textContent?.trim() || "";
-  if (pre) return pre.textContent?.trim() || "";
+  if (pre) return serializeMermaidFromNode(pre).trim();
   return serializeMermaidFromNode(container).trim();
 }
 async function renderMermaid() {
-  if (!mermaidContainer.value || !mermaidDefinition) return;
+  if (!mermaidContainer.value || !mermaidDefinition.value) return;
   isLoading.value = true;
   const performRender = async () => {
     if (!mermaidContainer.value) return;
     hasError.value = false;
     errorContent.value = null;
+    const startTime = performance.now();
     try {
       const mermaid = await $mermaid();
-      const initOptions = {
-        startOnLoad: false,
-        ...baseMermaidInit,
-        theme: mermaidTheme.value
-      };
-      mermaid.initialize(initOptions);
+      mermaid.initialize(effectiveMermaidInit.value);
       mermaidContainer.value.removeAttribute("data-processed");
-      mermaidContainer.value.textContent = mermaidDefinition;
+      mermaidContainer.value.textContent = mermaidDefinition.value;
       await nextTick();
       await mermaid.run({
         nodes: [mermaidContainer.value],
-        suppressErrors: true
+        suppressErrors: !debug
       });
       hasRenderedOnce.value = true;
-      await new Promise((resolve) => setTimeout(resolve, 5));
+      if (debug) {
+        const endTime = performance.now();
+        console.log(`[nuxt-content-mermaid] \u23F1\uFE0F  Rendered in ${(endTime - startTime).toFixed(2)}ms`);
+      }
     } catch (error) {
       console.error("[nuxt-content-mermaid]", error);
       hasError.value = true;
@@ -158,13 +224,11 @@ async function renderMermaid() {
       isLoading.value = false;
     }
   };
-  await enqueueRender(performRender);
+  await enqueueRender(performRender, debug);
 }
 function setupMermaidContainer() {
   const container = mermaidContainer.value;
   if (!container) return;
-  if (!mermaidDefinition)
-    mermaidDefinition = extractMermaidDefinition(container);
   if (!isLazy) {
     renderMermaid();
     return;
@@ -182,8 +246,8 @@ function setupMermaidContainer() {
 }
 onMounted(() => {
   if (!isEnabled) return;
-  if (mermaidContainer.value)
-    mermaidDefinition = extractMermaidDefinition(mermaidContainer.value);
+  if (!mermaidDefinition.value && mermaidContainer.value)
+    mermaidDefinition.value = extractMermaidDefinition(mermaidContainer.value);
   nextTick(() => setupMermaidContainer());
 });
 onUnmounted(() => {
@@ -193,6 +257,19 @@ watch(mermaidTheme, () => {
   if (!isEnabled) return;
   if (hasRenderedOnce.value) renderMermaid();
 });
+watch(
+  frontmatterConfig,
+  () => {
+    if (!isEnabled) return;
+    if (hasRenderedOnce.value) renderMermaid();
+  },
+  { deep: true }
+);
+watch(decodedCode, (newCode) => {
+  if (!isEnabled) return;
+  mermaidDefinition.value = newCode;
+  if (hasRenderedOnce.value) renderMermaid();
+});
 </script>
 
 <template>
@@ -210,8 +287,11 @@ watch(mermaidTheme, () => {
       :is="customMermaidImpl"
       v-else-if="customMermaidImpl"
       :spinner="spinnerComponent"
+      :code="decodedCode"
     >
-      <slot />
+      <slot>
+        <pre v-if="decodedCode"><code>{{ decodedCode }}</code></pre>
+      </slot>
     </component>
 
     <div
@@ -220,7 +300,9 @@ watch(mermaidTheme, () => {
     >
       <div ref="mermaidContainer">
         <!-- Initially show the slot's <pre><code> for SSR; client-side rendering will replace it with the mermaid SVG -->
-        <slot />
+        <slot>
+          <pre v-if="decodedCode"><code>{{ decodedCode }}</code></pre>
+        </slot>
       </div>
 
       <template v-if="isLoading && !hasRenderedOnce">
@@ -254,5 +336,5 @@ watch(mermaidTheme, () => {
 </template>
 
 <style scoped>
-.mermaid-wrapper{align-items:center;display:flex;justify-content:center;position:relative}.mermaid-wrapper :deep(code),.mermaid-wrapper :deep(pre){margin:0;max-height:160px;opacity:0;overflow:hidden;pointer-events:none;-webkit-user-select:none;-moz-user-select:none;user-select:none}.mermaid-error-default{text-align:center}.mermaid:not([data-processed]){color:transparent;min-height:10px}.mermaid{display:flex;justify-content:center}.mermaid .edgeLabel,.mermaid .label,.mermaid .nodeLabel{overflow:visible!important;white-space:normal!important}.mermaid foreignObject{overflow:visible!important}
+.mermaid-wrapper{position:relative;text-align:center}.mermaid-wrapper :deep(code),.mermaid-wrapper :deep(pre){margin:0;max-height:160px;opacity:0;overflow:hidden;pointer-events:none;-webkit-user-select:none;-moz-user-select:none;user-select:none}.mermaid-error-default{text-align:center}.mermaid:not([data-processed]){color:transparent;min-height:10px}.mermaid-wrapper :deep(.edgeLabel),.mermaid-wrapper :deep(.label),.mermaid-wrapper :deep(.nodeLabel){overflow:visible!important;white-space:normal!important}.mermaid-wrapper :deep(foreignObject){overflow:visible!important}
 </style>

package/dist/runtime/components/Mermaid.vue.d.ts

@@ -1,3 +1,8 @@
+import type { MermaidConfig } from 'mermaid';
+type __VLS_Props = {
+    config?: MermaidConfig | string | unknown;
+    code?: string;
+};
 declare var __VLS_1: {}, __VLS_9: {}, __VLS_11: {}, __VLS_13: {}, __VLS_21: {
     error: unknown;
     source: string;
@@ -13,7 +18,7 @@ type __VLS_Slots = {} & {
 } & {
     error?: (props: typeof __VLS_21) => any;
 };
-declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/runtime/constants.d.ts

@@ -1,5 +1,5 @@
 import type { MermaidConfig } from 'mermaid';
-export declare const DEFAULT_IMPORT_SOURCE = "https://cdn.jsdelivr.net/npm/mermaid@11.12.1/dist/mermaid.esm.min.mjs";
 export declare const DEFAULT_LIGHT_THEME: MermaidConfig['theme'];
 export declare const DEFAULT_DARK_THEME: MermaidConfig['theme'];
-export declare const DEFAULT_MERMAID_INIT: MermaidConfig;
+export declare const DEFAULT_MERMAID_CONFIG: MermaidConfig;
+export declare const DEFAULT_FRONTMATTER_CONFIG_KEY = "config";

package/dist/runtime/constants.js

@@ -1,6 +1,10 @@
-export const DEFAULT_IMPORT_SOURCE = "https://cdn.jsdelivr.net/npm/mermaid@11.12.1/dist/mermaid.esm.min.mjs";
 export const DEFAULT_LIGHT_THEME = "default";
 export const DEFAULT_DARK_THEME = "dark";
-export const DEFAULT_MERMAID_INIT = {
-  startOnLoad: false
+export const DEFAULT_MERMAID_CONFIG = {
+  startOnLoad: false,
+  theme: "default",
+  fontFamily: "Arial, sans-serif, \u5FAE\u8EDF\u6B63\u9ED1\u9AD4",
+  securityLevel: "strict",
+  logLevel: "error"
 };
+export const DEFAULT_FRONTMATTER_CONFIG_KEY = "config";

package/dist/runtime/mermaid-config.d.ts

@@ -0,0 +1,17 @@
+import type { MermaidConfig } from 'mermaid';
+interface ThemeOptions {
+    useColorModeTheme?: boolean;
+    colorModeValue?: string;
+    baseTheme?: MermaidConfig['theme'];
+    lightTheme?: MermaidConfig['theme'];
+    darkTheme?: MermaidConfig['theme'];
+    frontmatterTheme?: MermaidConfig['theme'];
+}
+export declare function resolveMermaidTheme(options: ThemeOptions): "default" | "base" | "dark" | "forest" | "neutral" | "null" | undefined;
+interface MergeOptions extends MermaidConfig {
+    baseConfig?: MermaidConfig;
+    overrideConfig?: MermaidConfig;
+    theme?: MermaidConfig['theme'];
+}
+export declare function mergeMermaidConfig(options: MergeOptions): MermaidConfig;
+export {};

package/dist/runtime/mermaid-config.js

@@ -0,0 +1,36 @@
+import { defu } from "defu";
+export function resolveMermaidTheme(options) {
+  const {
+    useColorModeTheme,
+    colorModeValue,
+    frontmatterTheme,
+    baseTheme,
+    lightTheme,
+    darkTheme
+  } = options;
+  if (frontmatterTheme) return frontmatterTheme;
+  if (useColorModeTheme && colorModeValue) {
+    if (colorModeValue === "dark" && darkTheme) return darkTheme;
+    if (colorModeValue !== "dark" && lightTheme) return lightTheme;
+  }
+  return baseTheme ?? lightTheme ?? darkTheme;
+}
+export function mergeMermaidConfig(options) {
+  const {
+    baseConfig,
+    overrideConfig,
+    theme,
+    ...overrides
+  } = options;
+  const merged = defu(
+    {},
+    overrides || {},
+    overrideConfig || {},
+    baseConfig || {}
+  );
+  return {
+    startOnLoad: false,
+    ...merged,
+    theme: theme ?? merged.theme
+  };
+}

package/dist/runtime/plugins/mermaid.client.js

@@ -1,27 +1,9 @@
 import { defineNuxtPlugin, useRuntimeConfig } from "#app";
-import {
-  DEFAULT_IMPORT_SOURCE,
-  DEFAULT_MERMAID_INIT
-} from "../constants.js";
+import { DEFAULT_MERMAID_CONFIG } from "../constants.js";
 const globalWithLoader = globalThis;
-const ABSOLUTE_URL_REGEX = /^(?:https?:)?\/\//;
-function resolveSource(source) {
-  if (ABSOLUTE_URL_REGEX.test(source)) return source;
-  if (source.startsWith("/")) return source;
-  if (typeof window !== "undefined")
-    return new URL(source, window.location.origin).href;
-  return source;
-}
-async function loadMermaidFrom(source) {
-  const mod = await import(
-    /* @vite-ignore */
-    resolveSource(source)
-  );
-  return mod.default ?? mod;
-}
 export default defineNuxtPlugin(() => {
   const runtimeConfig = useRuntimeConfig();
-  const mermaidConfig = runtimeConfig.public?.mermaidContent;
+  const mermaidConfig = runtimeConfig.public?.contentMermaid ?? runtimeConfig.public?.mermaidContent ?? {};
   if (mermaidConfig?.enabled === false) {
     return {
       provide: {
@@ -36,18 +18,27 @@ export default defineNuxtPlugin(() => {
   const loadMermaid = async () => {
     if (globalWithLoader.__nuxtMermaidLoader__)
       return globalWithLoader.__nuxtMermaidLoader__;
-    const importSource = mermaidConfig?.loader?.importSource || DEFAULT_IMPORT_SOURCE;
+    const debug = mermaidConfig?.debug || false;
+    const userInit = mermaidConfig?.loader?.init || {};
+    const hasUserLogLevel = Object.prototype.hasOwnProperty.call(userInit, "logLevel");
+    const hasUserSuppressErrorRendering = Object.prototype.hasOwnProperty.call(userInit, "suppressErrorRendering");
     const initOptions = {
-      ...DEFAULT_MERMAID_INIT,
-      ...mermaidConfig?.loader?.init
+      ...DEFAULT_MERMAID_CONFIG,
+      ...userInit,
+      logLevel: hasUserLogLevel ? userInit.logLevel : debug ? 1 : 5,
+      suppressErrorRendering: hasUserSuppressErrorRendering ? userInit.suppressErrorRendering : !debug
     };
-    globalWithLoader.__nuxtMermaidLoader__ = loadMermaidFrom(importSource).then((mermaid) => {
-      mermaid.initialize(initOptions);
-      return mermaid;
-    }).catch((error) => {
-      globalWithLoader.__nuxtMermaidLoader__ = void 0;
-      throw error;
-    });
+    globalWithLoader.__nuxtMermaidLoader__ = (async () => {
+      try {
+        const mermaid = await import("mermaid");
+        const mermaidInstance = mermaid.default ?? mermaid;
+        mermaidInstance.initialize(initOptions);
+        return mermaidInstance;
+      } catch (error) {
+        globalWithLoader.__nuxtMermaidLoader__ = void 0;
+        throw error;
+      }
+    })();
     return globalWithLoader.__nuxtMermaidLoader__;
   };
   return {

package/dist/runtime/utils.d.ts

@@ -1 +1 @@
-export declare function enqueueRender(task: () => Promise<void>): Promise<void>;
+export declare function enqueueRender(task: () => Promise<void>, debug?: boolean): Promise<void>;

package/dist/runtime/utils.js

@@ -1,7 +1,30 @@
 let renderQueue = Promise.resolve();
-export function enqueueRender(task) {
-  renderQueue = renderQueue.then(task).catch((e) => {
-    console.error("[nuxt-content-mermaid] Render error:", e);
+let queueSize = 0;
+export function enqueueRender(task, debug = false) {
+  queueSize++;
+  if (debug) {
+    console.log(`[nuxt-content-mermaid] \u{1F535} Enqueueing task. Queue size: ${queueSize}`);
+  }
+  const wrappedTask = async () => {
+    if (debug) {
+      console.log(`[nuxt-content-mermaid] \u{1F7E2} Starting render task. Pending: ${queueSize - 1}`);
+    }
+    try {
+      await task();
+    } catch (e) {
+      console.error("[nuxt-content-mermaid] Render error:", e);
+      throw e;
+    } finally {
+      queueSize--;
+      if (debug) {
+        console.log(`[nuxt-content-mermaid] \u2705 Task finished. Remaining: ${queueSize}`);
+      }
+    }
+  };
+  renderQueue = renderQueue.then(wrappedTask).catch((e) => {
+    if (debug) {
+      console.error("[nuxt-content-mermaid] \u274C Queue chain caught error:", e);
+    }
   });
   return renderQueue;
 }

package/dist/types.d.mts

@@ -1,3 +1,3 @@
-export { default } from './module.mjs'
+export { default, type transformMermaidCodeBlocks } from './module.mjs'
 
 export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barzhsieh/nuxt-content-mermaid",
-  "version": "1.0.4",
+  "version": "2.0.0",
   "description": "A Nuxt module designed for integrating Mermaid with `@nuxt/content`. It automatically converts `mermaid` code blocks in Markdown into responsive chart components, and supports lazy loading and dark/light theme switching.",
   "keywords": [
     "nuxt",
@@ -37,28 +37,29 @@
   ],
   "dependencies": {
     "@nuxt/kit": "4.2.1",
-    "defu": "^6.1.4"
+    "defu": "^6.1.4",
+    "mermaid": "^11.12.2"
   },
   "peerDependencies": {
-    "nuxt": "^3.20.1 || ^4.1.0",
-    "@nuxt/content": ">=3.5.0"
+    "@nuxt/content": ">=3.5.0",
+    "nuxt": "^3.20.1 || ^4.1.0"
   },
   "devDependencies": {
-    "@nuxt/content": "3.8.0",
+    "@nuxt/content": "^3.9.0",
     "@nuxt/devtools": "3.1.1",
     "@nuxt/eslint-config": "1.11.0",
     "@nuxt/module-builder": "1.0.2",
     "@nuxt/schema": "4.2.1",
-    "@nuxt/test-utils": "3.20.1",
+    "@nuxt/test-utils": "^3.21.0",
     "@nuxtjs/color-mode": "4.0.0",
-    "@types/node": "latest",
+    "@types/node": "^24.10.1",
     "changelogen": "^0.6.2",
     "eslint": "^9.39.1",
-    "mermaid": "^11.12.1",
     "nuxt": "4.2.1",
+    "playwright": "^1.57.0",
     "typescript": "~5.9.3",
-    "vitest": "^4.0.14",
-    "vue-tsc": "^3.1.4"
+    "vitest": "^4.0.15",
+    "vue-tsc": "^3.1.7"
   },
   "volta": {
     "node": "22.21.1"