@barzhsieh/nuxt-content-mermaid 2.0.1 → 2.1.0-alpha.0

package/README.md

@@ -95,7 +95,6 @@ export default defineNuxtConfig({
       lazy: true,
     },
     theme: {
-      useColorModeTheme: true,
       light: "default",
       dark: "dark",
     },
@@ -126,11 +125,12 @@ export default defineNuxtConfig({
 
 **theme**
 
-| Option                      | Type    | Default     | Description                                                                                               |
-| :-------------------------- | :------ | :---------- | :-------------------------------------------------------------------------------------------------------- |
-| `theme.useColorModeTheme`   | boolean | `true`      | If `@nuxtjs/color-mode` is installed, automatically follow its current theme.                             |
-| `theme.light`               | string  | `'default'` | Mermaid theme to use when color mode is light (and as fallback when color-mode is off).                   |
-| `theme.dark`                | string  | `'dark'`    | Mermaid theme to use when color mode is dark (and as fallback when color-mode is off).                    |
+Color mode integration is automatic when `@nuxtjs/color-mode` is installed; manual themes set via `useMermaidTheme()` take precedence.
+
+| Option            | Type   | Default     | Description                                                                                 |
+| :---------------- | :----- | :---------- | :------------------------------------------------------------------------------------------ |
+| `theme.light`     | string | `'default'` | Mermaid theme to use when color mode is light (and as fallback when color-mode is missing). |
+| `theme.dark`      | string | `'dark'`    | Mermaid theme to use when color mode is dark (and as fallback when color-mode is missing).  |
 
 **components**
 
@@ -157,16 +157,43 @@ export default defineNuxtConfig({
 
 The module determines the active Mermaid theme with the following priority:
 
-1. If `theme.useColorModeTheme: true` _and_ `@nuxtjs/color-mode` is available:  
-   - `dark` → `theme.dark`  
-   - `light` → `theme.light`
-2. Otherwise (color-mode missing or `theme.useColorModeTheme` is `false`):  
-   - Use `loader.init.theme` if provided.  
-   - Else fall back to `theme.light`, then `theme.dark`.
+1. Frontmatter `config.theme` (per-page override)
+2. Manual mode via `useMermaidTheme()` (if set)
+3. `@nuxtjs/color-mode` (auto-detected when installed):
+  - `dark` → `theme.dark`
+  - `light` → `theme.light`
+4. `loader.init.theme` (if provided)
+5. Fallback: `theme.light`, then Mermaid default `'default'`
+
+For advanced manual control (e.g., forcing specific themes, custom toggle logic), please refer to the [Manual Theme Control Guide](./docs/en/MANUAL_THEME_CONTROL.md).
 
 ### Override Per-Page Settings with Frontmatter
 
 Each Markdown file can override module settings by adding a `config` field in the frontmatter.
+
+> **⚠️ To use frontmatter `config` overrides, you MUST declare the `config` field in your collection schema in `content.config.ts`.**
+> Without this, Nuxt Content will not parse the `config` field as a JSON object, and your overrides will not work.
+
+Add this to your `content.config.ts`:
+
+```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(),
+    }),
+  },
+})
+```
+
+Then use it in your Markdown frontmatter:
+
 ````markdown
 ---
 title: Example of Overriding Mermaid Settings Per Page
@@ -181,24 +208,6 @@ flowchart LR
 ```
 ````
 
-> **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:

package/README.zh-TW.md

@@ -95,7 +95,6 @@ export default defineNuxtConfig({
       lazy: true,
     },
     theme: {
-      useColorModeTheme: true,
       light: "default",
       dark: "dark",
     },
@@ -126,11 +125,12 @@ export default defineNuxtConfig({
 
 **theme**
 
-| 參數                        | 類型    | 預設值      | 說明                                                                                                    |
-| :-------------------------- | :------ | :---------- | :------------------------------------------------------------------------------------------------------ |
-| `theme.useColorModeTheme`   | boolean | `true`      | 若安裝了 `@nuxtjs/color-mode`，是否自動跟隨其主題。                                                    |
-| `theme.light`               | string  | `'default'` | 當 `colorMode` 為 light 時的主題，也可作為 fallback。                                                   |
-| `theme.dark`                | string  | `'dark'`    | 當 `colorMode` 為 dark 時的主題，也可作為 fallback。                                                    |
+若專案安裝了 `@nuxtjs/color-mode` 會自動偵測並跟隨；透過 `useMermaidTheme()` 設定的手動主題會優先。
+
+| 參數          | 類型   | 預設值      | 說明                                                                              |
+| :------------ | :----- | :---------- | :-------------------------------------------------------------------------------- |
+| `theme.light` | string | `'default'` | 當 color-mode 為 light 時的主題，若 color-mode 不存在也會回退使用。               |
+| `theme.dark`  | string | `'dark'`    | 當 color-mode 為 dark 時的主題，若 color-mode 不存在也會回退使用。                |
 
 **components**
 
@@ -153,21 +153,47 @@ export default defineNuxtConfig({
     - **Debug 關閉**：`mermaid.run` 使用 `suppressErrors: true`，避免單一圖表錯誤中斷其他圖表的渲染。
   - **主控台輸出**：模組會額外輸出渲染佇列的診斷資訊與執行時間統計。
 
-### 主題與顏色模式 (Color Mode)
+### 主題與顏色模式 (Theme & Color Mode)
 
 模組會依據以下優先順序決定主題：
 
-1. 若 `theme.useColorModeTheme: true`，且專案有安裝 `@nuxtjs/color-mode`：  
-   - 偵測為 `dark` → 使用 `theme.dark`  
-   - 偵測為 `light` → 使用 `theme.light`
-2. 否則（color-mode 未安裝或 `theme.useColorModeTheme` 為 `false`）：  
-   - 優先使用 `loader.init.theme`。  
-   - 若未提供，依序回退至 `theme.light`，若沒有設置則會回退至 `theme.dark`。
+1. Frontmatter `config.theme`（單篇覆寫）
+2. `useMermaidTheme()` 設定的手動模式（若有）
+3. `@nuxtjs/color-mode`（安裝時自動偵測）：
+  - `dark` → 使用 `theme.dark`
+  - `light` → 使用 `theme.light`
+4. `loader.init.theme`（若有設定）
+5. 回退：`theme.light`，若無則 Mermaid 預設 `'default'`
+
+更多進階手動控制（如：強制指定特定主題、自訂切換邏輯），請參閱 [手動主題控制指南](./docs/ch/MANUAL_THEME_CONTROL.md)。
 
 ### 以 frontmatter 覆寫單頁設定
 
 每篇 Markdown 都可以透過於 frontmatter 中加入 `config` 欄位來覆寫模組設定。
 
+> **⚠️ 若要使用 frontmatter `config` 覆寫，務必在 `content.config.ts` 的 collection schema 中宣告 `config` 欄位。**  
+> 若未宣告，Nuxt Content 不會將 `config` 解析為 JSON 物件，覆寫將無法生效。
+
+在 `content.config.ts` 加上：
+
+```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(),
+    }),
+  },
+})
+```
+
+接著在 Markdown frontmatter 使用：
+
 ````markdown
 ---
 title: 單篇覆寫 Mermaid 設定範例
@@ -183,24 +209,6 @@ flowchart LR
 ```
 ````
 
-> **重要：如果要使用 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: ...}%%` 語法覆寫設定，例如：

package/dist/module.d.mts

@@ -34,8 +34,8 @@ interface ModuleOptions {
      */
     theme?: {
         /**
-         * Whether to sync Mermaid theme with @nuxtjs/color-mode
-         * @default true
+         * @deprecated The module now automatically detects and syncs with @nuxtjs/color-mode.
+         * This option no longer has any effect and will be removed in a future version.
          */
         useColorModeTheme?: boolean;
         light?: MermaidConfig['theme'];

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.20.1 || ^4.1.0"
   },
-  "version": "2.0.1",
+  "version": "2.1.0-alpha.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -11,7 +11,6 @@ const DEFAULTS = {
     lazy: true
   },
   theme: {
-    useColorModeTheme: true,
     light: DEFAULT_LIGHT_THEME,
     dark: DEFAULT_DARK_THEME
   },

package/dist/runtime/components/Mermaid.vue

@@ -12,6 +12,7 @@ import {
 } from "vue";
 import { mergeMermaidConfig, resolveMermaidTheme } from "../mermaid-config";
 import { enqueueRender } from "../utils";
+import { useMermaidTheme } from "../composables/useMermaidTheme";
 import Spinner from "./Spinner.vue";
 const props = defineProps({
   config: { type: null, required: false },
@@ -29,11 +30,11 @@ const lazyOption = loaderOptions.lazy;
 const isLazy = lazyOption !== false;
 const lazyThreshold = typeof lazyOption === "object" && typeof lazyOption.threshold === "number" ? lazyOption.threshold : 0.1;
 const baseMermaidInit = loaderOptions.init || {};
-const useColorModeTheme = themeOptions.useColorModeTheme;
 const lightTheme = themeOptions.light;
 const darkTheme = themeOptions.dark;
 const colorMode = nuxtApp.$colorMode;
 const { $mermaid } = nuxtApp;
+const { currentTheme: manualThemeMode } = useMermaidTheme();
 const mermaidContainer = useTemplateRef("mermaidContainer");
 const hasRenderedOnce = ref(false);
 const isLoading = ref(false);
@@ -47,9 +48,9 @@ const frontmatterConfig = computed(() => {
   if (!value)
     return void 0;
   if (typeof value !== "object") {
-    if (import.meta.dev) {
+    if (import.meta.dev && value !== null && value !== void 0) {
       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.",
+        "[nuxt-content-mermaid] Received 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
       );
     }
@@ -59,8 +60,8 @@ const frontmatterConfig = computed(() => {
 });
 const mermaidTheme = computed(() => {
   return resolveMermaidTheme({
-    useColorModeTheme,
     colorModeValue: colorMode?.value,
+    manualThemeMode: manualThemeMode.value,
     frontmatterTheme: frontmatterConfig.value?.theme,
     baseTheme: baseMermaidInit.theme,
     lightTheme,

package/dist/runtime/composables/useMermaidTheme.d.ts

@@ -0,0 +1,48 @@
+import type { MermaidConfig } from 'mermaid';
+/**
+ * 簡寫模式主題，用於快速切換配置的 light/dark 主題
+ * - 'light': 對應 contentMermaid.theme.light 設定
+ * - 'dark': 對應 contentMermaid.theme.dark 設定
+ * @see https://mermaid.js.org/ecosystem/integrations.html
+ */
+export type SimpleMermaidTheme = 'light' | 'dark';
+/**
+ * Mermaid 主題類型
+ * 可以是：
+ * - 簡寫模式: 'light', 'dark' (對應配置的 light/dark 主題)
+ * - 官方主題: 'default', 'forest', 'dark', 'neutral', 'base' 等
+ * - null: 重置為自動模式
+ */
+export type MermaidThemeMode = MermaidConfig['theme'] | SimpleMermaidTheme | null;
+/**
+ * Composable for managing Mermaid theme independently of @nuxtjs/color-mode
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const { setMermaidTheme, currentTheme } = useMermaidTheme()
+ *
+ * function toggleTheme() {
+ *   setMermaidTheme(currentTheme.value === 'dark' ? 'light' : 'dark')
+ * }
+ * </script>
+ * ```
+ */
+export declare function useMermaidTheme(): {
+    /**
+     * The current manual theme mode (reactive ref)
+     */
+    currentTheme: import("vue").Ref<MermaidThemeMode, MermaidThemeMode>;
+    /**
+     * Set the Mermaid theme manually
+     */
+    setMermaidTheme: (mode: MermaidThemeMode) => void;
+    /**
+     * Get the current manual theme mode
+     */
+    getMermaidTheme: () => MermaidThemeMode;
+    /**
+     * Reset to automatic theme mode
+     */
+    resetMermaidTheme: () => void;
+};

package/dist/runtime/composables/useMermaidTheme.js

@@ -0,0 +1,31 @@
+import { useState } from "#app";
+export function useMermaidTheme() {
+  const manualThemeMode = useState("mermaid-theme-mode", () => null);
+  function setMermaidTheme(mode) {
+    manualThemeMode.value = mode;
+  }
+  function getMermaidTheme() {
+    return manualThemeMode.value;
+  }
+  function resetMermaidTheme() {
+    manualThemeMode.value = null;
+  }
+  return {
+    /**
+     * The current manual theme mode (reactive ref)
+     */
+    currentTheme: manualThemeMode,
+    /**
+     * Set the Mermaid theme manually
+     */
+    setMermaidTheme,
+    /**
+     * Get the current manual theme mode
+     */
+    getMermaidTheme,
+    /**
+     * Reset to automatic theme mode
+     */
+    resetMermaidTheme
+  };
+}

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

@@ -1,13 +1,14 @@
 import type { MermaidConfig } from 'mermaid';
+import type { MermaidThemeMode } from './composables/useMermaidTheme.js';
 interface ThemeOptions {
-    useColorModeTheme?: boolean;
     colorModeValue?: string;
+    manualThemeMode?: MermaidThemeMode;
     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;
+export declare function resolveMermaidTheme(options: ThemeOptions): "default" | "base" | "dark" | "forest" | "neutral" | "null";
 interface MergeOptions extends MermaidConfig {
     baseConfig?: MermaidConfig;
     overrideConfig?: MermaidConfig;

package/dist/runtime/mermaid-config.js

@@ -1,19 +1,27 @@
 import { defu } from "defu";
 export function resolveMermaidTheme(options) {
   const {
-    useColorModeTheme,
     colorModeValue,
+    manualThemeMode,
     frontmatterTheme,
     baseTheme,
     lightTheme,
     darkTheme
   } = options;
   if (frontmatterTheme) return frontmatterTheme;
-  if (useColorModeTheme && colorModeValue) {
-    if (colorModeValue === "dark" && darkTheme) return darkTheme;
-    if (colorModeValue !== "dark" && lightTheme) return lightTheme;
+  if (manualThemeMode) {
+    if (manualThemeMode === "dark") return darkTheme ?? "dark";
+    if (manualThemeMode === "light") return lightTheme ?? "default";
+    return manualThemeMode;
   }
-  return baseTheme ?? lightTheme ?? darkTheme;
+  if (colorModeValue) {
+    if (colorModeValue === "dark") {
+      return darkTheme ?? "dark";
+    } else {
+      return lightTheme ?? "default";
+    }
+  }
+  return baseTheme ?? lightTheme ?? "default";
 }
 export function mergeMermaidConfig(options) {
   const {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barzhsieh/nuxt-content-mermaid",
-  "version": "2.0.1",
+  "version": "2.1.0-alpha.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",
@@ -72,6 +72,9 @@
     "release:patch": "pnpm run release:base && changelogen --release --patch --push && pnpm publish",
     "release:minor": "pnpm run release:base && changelogen --release --minor --push && pnpm publish",
     "release:major": "pnpm run release:base && changelogen --release --major --push && pnpm publish",
+    "release:minor:alpha": "pnpm run release:base && changelogen --release --preminor alpha --push && pnpm publish --tag alpha",
+    "release:minor:beta": "pnpm run release:base && changelogen --release --preminor beta --push && pnpm publish --tag beta",
+    "release:minor:rc": "pnpm run release:base && changelogen --release --preminor rc --push && pnpm publish --tag rc",
     "release": "pnpm run release:patch",
     "lint": "eslint .",
     "test": "vitest run",