@barzhsieh/nuxt-content-mermaid 2.2.3 → 3.0.0

package/README.md

@@ -14,54 +14,111 @@
 A Nuxt module designed for integrating [**Mermaid**](https://mermaid.js.org/) with [**Nuxt Content v3**](https://content.nuxt.com/docs/getting-started).
 It automatically converts `mermaid` code blocks in Markdown into responsive chart components, and supports lazy loading and dark/light theme switching.
 
+<details>
+<summary>Table of Contents</summary>
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Dependency and Migration Contract](./docs/en/DEPENDENCY_AND_MIGRATION_CONTRACT.md)
+- [Quick Setup](#quick-setup)
+- [Configuration](#configuration)
+- [Migrating to v3](#migrating-to-v3)
+- [Styling (CSS Variables)](#styling-css-variables)
+- [Advanced Usage](#advanced-usage)
+  - [Debug mode](#debug-mode)
+  - [Theme & Color Mode](#theme--color-mode)
+  - [Override Per-Page Settings with Frontmatter](#override-per-page-settings-with-frontmatter)
+  - [Mermaid Inline Attributes & YAML Frontmatter](#mermaid-inline-attributes--yaml-frontmatter)
+  - [Custom Rendering Component](#custom-rendering-component)
+  - [Wrapper Example](#wrapper-example)
+  - [Error Handling](#error-handling)
+- [Support](#support)
+- [Contribution](#contribution)
+- [License](#license)
+
+</details>
+
 ## Features
 
 - **Automatic conversion**: Parses Markdown code blocks and replaces them with a `<Mermaid>` rendering component.
 - **Performance friendly**: Supports lazy loading — Mermaid core and related resources are only loaded when the component mounts.
 - **Theme integration**: Integrates with `@nuxtjs/color-mode` to automatically switch between light and dark Mermaid themes.
-- **Highly customizable**: Allows custom wrapper components, loading spinners, error views, and custom CDN or local import sources.
-- **Runtime config**: Settings can be overridden at deployment time through runtime config / environment variables.
+- **Highly customizable**: Supports custom renderers, loading spinners, error views, themes, and toolbar controls.
+- **Deployment configuration**: Pure-data settings can be transported through public runtime config and are resolved once for each Nuxt application.
 
 ## Requirements
 
-- `nuxt@^3.20.1 || ^4.1.0`
-- `@nuxt/content@>=3.5.0`
+- Node.js `>=22.19.0`
+- `nuxt@^4.1.0`
+- `@nuxt/content@>=3.5.0 <4.0.0`
 
-## Quick Setup
-
-### 1. Install the module
+For the ownership model, 2.x migration path, rendering guarantees, and visual
+snapshot limits, see the [Dependency and Migration Contract](./docs/en/DEPENDENCY_AND_MIGRATION_CONTRACT.md).
 
-**Auto-setup (adds to `modules` automatically):**
-
-```bash
-npx nuxi module add @barzhsieh/nuxt-content-mermaid
-```
+## Quick Setup
 
-> Nuxt CLI installs third-party modules as regular `dependencies` by default. If you prefer `devDependencies`, move it after install or use the manual option below.
+### 1. Install the packages
 
-**Install as dev dependency (manual modules entry):**
+Package-manager installation and Nuxt module initialization are separate
+steps. Your application owns the Nuxt and Nuxt Content peer dependencies, so it
+must install, pin, and update them. Install this module together with the
+supported Nuxt Content peer:
 
 ```bash
 # pnpm
-pnpm add -D @barzhsieh/nuxt-content-mermaid
+pnpm add @barzhsieh/nuxt-content-mermaid @nuxt/content
 
 # npm
-npm install -D @barzhsieh/nuxt-content-mermaid
+npm install @barzhsieh/nuxt-content-mermaid @nuxt/content
 
 # yarn
-yarn add -D @barzhsieh/nuxt-content-mermaid
+yarn add @barzhsieh/nuxt-content-mermaid @nuxt/content
 ```
 
-### 2. Configure `nuxt.config.ts`
+Mermaid is bundled as this module's Module-Owned Dependency, so you do not need
+to install it separately for this module.
 
-Make sure the module is included in the `modules` array (skip if you used `nuxi module add`):
+> [!NOTE]
+> **Nuxt Content database connector** — On Node.js, Nuxt Content asks the
+> application to choose a database connector. `better-sqlite3`, `sqlite3`, and
+> native SQLite in supported Node.js versions are available choices; this
+> module does not require or own a specific connector. Follow the
+> [Nuxt Content installation guide](https://content.nuxt.com/docs/getting-started/installation)
+> for the options supported by your installed version.
+>
+> **pnpm v10+** — If you choose `better-sqlite3` or `sqlite3`, pnpm v10 blocks
+> their native build scripts by default. Run `pnpm approve-builds`, or allow
+> only the connector you selected in `package.json`. The example below uses
+> `better-sqlite3`; replace it with `sqlite3` when that is your connector:
+>
+> ```json
+> {
+>   "pnpm": {
+>     "onlyBuiltDependencies": ["better-sqlite3"]
+>   }
+> }
+> ```
+
+### 2. Initialize the Nuxt module
+
+List only this module in the standard `modules` configuration:
 
 ```ts
 export default defineNuxtConfig({
-  modules: ["@barzhsieh/nuxt-content-mermaid", "@nuxt/content"],
+  modules: ["@barzhsieh/nuxt-content-mermaid"],
 });
 ```
 
+The module declares the required Nuxt Content relationship and compatible
+version through `moduleDependencies`, so Nuxt initializes the installed
+`@nuxt/content` module in the required order. This does not install, pin, or
+update Nuxt Content; those package-manager responsibilities remain with your
+application.
+
+If your application already lists `@nuxt/content` manually in `modules`, you
+may keep that entry. Manual listing remains supported, but it is no longer the
+standard configuration.
+
 ### 3. Use Mermaid in Markdown
 
 Add Mermaid code blocks inside `.md` files under the `content/` directory:
@@ -81,8 +138,7 @@ The module will automatically transform the block into an SVG chart component.
 
 ## Configuration
 
-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.)
+Configure the module globally through the canonical `contentMermaid` option. The former `mermaidContent` alias was removed in v3 and produces a migration error.
 
 ```ts
 // nuxt.config.ts
@@ -100,11 +156,6 @@ export default defineNuxtConfig({
       light: "default",
       dark: "dark",
     },
-    components: {
-      renderer: undefined,
-      spinner: undefined,
-      error: undefined,
-    },
     toolbar: {
       title: "mermaid",
       fontSize: "14px",
@@ -144,27 +195,42 @@ export default defineNuxtConfig({
 
 **loader**
 
-| 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. |
+| Option            | Type                                  | Default          | Description                                                                      |
+| :---------------- | :------------------------------------ | :--------------- | :------------------------------------------------------------------------------- |
+| `loader.init`     | `RuntimeMermaidConfig` (strict pure data) | package defaults | Pure-data Mermaid options transported to `mermaid.initialize`.                  |
+| `loader.lazy`     | `boolean \| { threshold?: number }` | `true`           | Lazy load Mermaid when the component enters the viewport; set `false` to preload. |
+
+The `loader.init` baseline is:
+
+```ts
+{
+  startOnLoad: false,
+  theme: 'default',
+  fontFamily: 'Arial, sans-serif, 微軟正黑體',
+  securityLevel: 'strict',
+}
+```
+
+When omitted, debug-derived values resolve to `logLevel: 5` and
+`suppressErrorRendering: true` with `debug: false`, or `logLevel: 1` and
+`suppressErrorRendering: false` with `debug: true`. Explicit values always win.
 
 **theme**
 
 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).  |
+| Option            | Type   | Default     | Description                                                                  |
+| :---------------- | :----- | :---------- | :--------------------------------------------------------------------------- |
+| `theme.light`     | string | `'default'` | Used for light color mode and the manual `setMermaidTheme('light')` strategy. |
+| `theme.dark`      | string | `'dark'`    | Used for dark color mode and the manual `setMermaidTheme('dark')` strategy.   |
 
 **components**
 
-| Option                    | Type     | Default     | Description                                                              |
-| :------------------------ | :------- | :---------- | :----------------------------------------------------------------------- |
-| `components.renderer`     | `string` | `undefined` | Optional: custom Mermaid renderer component name.                        |
-| `components.spinner`      | `string` | `undefined` | Optional: global loading spinner component name.                         |
-| `components.error`        | `string` | `undefined` | Optional: global error component name when Mermaid rendering fails.      |
+| Option                    | Type     | Default | Description                                                              |
+| :------------------------ | :------- | :------ | :----------------------------------------------------------------------- |
+| `components.renderer`     | `string` | omitted | Optional: custom Mermaid renderer component name.                        |
+| `components.spinner`      | `string` | omitted | Optional: global loading spinner component name.                         |
+| `components.error`        | `string` | omitted | Optional: global error component name when Mermaid rendering fails.      |
 
 **toolbar**
 
@@ -207,7 +273,11 @@ A zoom toolbar appears with +/−/Reset buttons and a percentage display.
 Use `toolbar.fullscreenToolbarScale` to scale the fullscreen toolbar and zoom controls.
 
 
-> **Note**: All options can be overridden at runtime via `runtimeConfig.public.contentMermaid` (`runtimeConfig.public.mermaidContent` remains supported but deprecated).
+> **Note**: `contentMermaid.enabled` controls Module Activation during Nuxt setup. Setting it to `false` disables only the Mermaid Content/runtime integration; it does not disable Nuxt Content. It is never a public runtime setting. `runtimeConfig.public.contentMermaid` carries only strict pure data and is resolved once during each Nuxt application initialization; mutating it later does not update the established Runtime Mermaid Snapshot.
+
+## Migrating to v3
+
+The [v3 migration guide](./docs/en/MIGRATION_V3.md) covers the removed configuration alias, build-time activation, pure-data runtime transport, Page versus Direct Mermaid Config, Property-Presence Merge, expand reset semantics, and public diagnostic and rendering guarantees. A runnable companion is available at `/migration` in the playground.
 
 ## Styling (CSS Variables)
 
@@ -264,7 +334,7 @@ Variables:
   - **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.
+  - **Console output**: Debug log wording and internal render scheduling are not public APIs. For configuration failures, recognize the documented public fingerprint instead of parsing private details.
 
 ### Theme & Color Mode
 
@@ -275,8 +345,7 @@ The module determines the active Mermaid theme with the following priority:
 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'`
+4. Resolved `loader.init.theme` (package 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).
 
@@ -394,12 +463,15 @@ graph TD
 
 If you want full control over rendering (for example to add a border, expand controls, or other UI), you can provide a custom component via `components.renderer`.
 
+The configured name is a candidate until its component resolves. Built-in rendering remains paused during resolution. If the component cannot be found or loaded, the module falls back to the Built-in Renderer. Once resolution succeeds, the Custom Renderer completely owns rendering; its later mount or render failures do not trigger Built-in fallback.
+
 1. Specify the component name in `nuxt.config.ts`:
 
    ```ts
    contentMermaid: {
      components: {
        renderer: "MyCustomMermaid",
+       spinner: "MySpinner", // optional input for your component
      },
    }
    ```
@@ -408,60 +480,60 @@ If you want full control over rendering (for example to add a border, expand con
 
    ```vue
    <script setup lang="ts">
-   // You can consume slot content or invoke useMermaid() logic here
+   import { onMounted, ref, shallowRef, useId } from 'vue'
+   import type { Component } from 'vue'
+
+   const props = defineProps<{
+     code?: string
+     spinner: Component | string
+   }>()
+
+   const loading = ref(true)
+   const error = shallowRef<unknown>()
+   const svg = ref('')
+   const renderId = `custom-mermaid-${useId().replaceAll(':', '')}`
+
+   onMounted(async () => {
+     try {
+       const mermaid = await useNuxtApp().$mermaid()
+       svg.value = (await mermaid.render(renderId, props.code ?? '')).svg
+     }
+     catch (cause) {
+       error.value = cause
+     }
+     finally {
+       loading.value = false
+     }
+   })
    </script>
 
    <template>
      <div class="custom-wrapper border rounded p-4">
-       <Mermaid>
-         <slot />
-       </Mermaid>
+       <component
+         :is="props.spinner"
+         v-if="loading"
+       />
+       <p
+         v-else-if="error"
+         role="alert"
+       >
+         Diagram failed: {{ error instanceof Error ? error.message : String(error) }}
+       </p>
+       <div
+         v-else
+         v-html="svg"
+       />
      </div>
    </template>
    ```
 
-#### Loading Indicator
+The Custom Renderer receives the existing `code`, default slot, and `spinner` inputs. It does not receive Built-in configuration, theme, toolbar, loading, or error state. `components.error` handles only Built-in Mermaid render failures, so a Custom Renderer must own its error presentation as shown above.
 
-The module renders a built-in spinner before the first Mermaid render. If you set `components.spinner`, the named component will replace the default spinner and will be passed into your custom renderer as a `spinner` prop.
-
-Minimal example that uses the provided spinner while waiting for your own loading logic:
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  contentMermaid: {
-    components: {
-      renderer: 'MyCustomMermaid',
-      spinner: 'MySpinner', // optional: globally replace the default spinner
-    },
-  },
-})
-```
-
-```vue
-<!-- components/MyCustomMermaid.vue -->
-<script setup lang="ts">
-import { ref, onMounted } from 'vue'
-import type { Component } from 'vue'
-
-const props = defineProps<{ spinner: Component | string }>()
-const loading = ref(true)
-onMounted(() => { loading.value = false })
-</script>
-
-<template>
-  <div class="my-mermaid">
-    <component v-if="loading" :is="props.spinner" />
-    <Mermaid v-else>
-      <slot />
-    </Mermaid>
-  </div>
-</template>
-```
+Do not render `<Mermaid>` from the component currently configured as `components.renderer`: that nested component would select the same Custom Renderer again. Invoke `$mermaid`, another rendering library, or your own renderer directly instead.
 
 ### Wrapper Example
 
-You can wrap `<Mermaid>` inside your own Vue component.
+Independently of `components.renderer`, you can wrap `<Mermaid>` inside your own Vue component. Do not configure that wrapper itself as the Custom Renderer.
 For example, you can bundle a title, loading state, and error/fallback UI, then drop it anywhere in templates:
 
 ```vue
@@ -531,16 +603,44 @@ export default defineNuxtConfig({
   },
 })
 ```
+
+## Compatibility
+
+The public peer contract supports Nuxt `^4.1.0` and Nuxt Content `>=3.5.0 <4.0.0`. Releases verify two fixed package artifact profiles: `v3-minimum` at the public floors and `v3-known-latest` at the deliberately pinned known-latest versions. Both profiles cover clean installation, public types, production build, and basic browser SVG rendering under their exact Node runtimes.
+
+These profiles are evidence for the complete peer range, not a list of the only supported versions. If a profile fails, the resolution is to diagnose and fix the compatibility boundary—not to remove that profile or weaken its Package User assertions.
+
+Run each profile under its exact Node runtime:
+
+```bash
+volta run --node 22.19.0 pnpm test:compatibility-profile --profile v3-minimum
+volta run --node 24.19.0 pnpm test:package-artifact
+```
+
+## Support
+
+If this module is useful to you, you can [support my open-source work on Ko-fi](https://ko-fi.com/barzhsieh). Your support helps fund maintenance, compatibility updates, testing, and documentation.
+
 ## Contribution
 
+Contributions are welcome! Feel free to open an [issue](https://github.com/andy820621/nuxt-content-mermaid/issues) or submit a pull request.
+
+Maintainers should follow the [stable release runbook](./docs/en/RELEASING.md).
+
+- Commit messages should follow [Conventional Commits](https://www.conventionalcommits.org/) (e.g. `feat: add spinner option`, `fix: handle dark mode toggle`).
+- PRs should include a summary of changes and test results.
+
 <details>
 <summary>Local Development Commands</summary>
 
 ```bash
-pnpm install
-pnpm dev:prepare
-pnpm dev       # Run playground
-pnpm test      # Run tests
+pnpm install        # Install dependencies
+pnpm dev:prepare    # Build module stubs & prepare playground
+pnpm dev            # Start playground
+pnpm test           # Run tests
+pnpm test:package-artifact # Verify the known-latest package artifact profile
+pnpm lint           # Run ESLint
+pnpm test:types     # Type checking
 ```
 
 </details>