@movk/nuxt-docs 1.12.4 → 1.13.0

package/README.md

@@ -41,7 +41,7 @@
 - ⚡ **基于 Nuxt 4** - 充分利用最新的 Nuxt 框架，实现卓越性能
 - 🎨 **采用 Nuxt UI** - 集成全面的 UI 组件库，开箱即用
 - 📝 **MDC 语法增强** - 支持 Markdown 与 Vue 组件的无缝集成
-- 📊 **Mermaid 图表** - 内置 Mermaid 支持，渲染流程图、时序图、类图等可视化图表，支持自动主题切换和全屏查看
+- 📊 **Mermaid 图表** - 可选按需启用，渲染流程图、时序图、类图等可视化图表，支持自动主题切换和全屏查看
 - 🔍 **全文搜索** - 基于 Nuxt Content 的 `ContentSearch` 组件，支持键盘快捷键（⌘K）
 - 🌙 **暗黑模式** - 支持亮色/暗色主题切换
 - 📱 **响应式设计** - 移动优先的响应式布局
@@ -180,7 +180,20 @@ icon: i-lucide-rocket
 
 ### Mermaid 图表
 
-使用 ` ```mermaid ` 代码块渲染可视化图表，支持流程图、时序图、类图等多种图表类型：
+Mermaid 是可选功能，默认不启用。先安装依赖，再开启配置：
+
+```bash
+pnpm add mermaid dompurify
+```
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  extends: ['@movk/nuxt-docs'],
+  mermaid: { enabled: true }
+})
+```
+
+启用后，使用 ` ```mermaid ` 代码块渲染可视化图表，支持流程图、时序图、类图等多种图表类型：
 
 ````md [md]
 ```mermaid
@@ -210,22 +223,7 @@ graph TD
 - **甘特图**（`gantt`）：用于展示项目时间线
 - **饼图**（`pie`）：用于展示数据占比
 - **Git 图**（`gitGraph`）：用于展示分支历史
-- 以及更多 [Mermaid 支持的图表类型](https://mermaid.js.org/intro/)
-
-**带文件名的图表：**
-
-````md [md]
-```mermaid [auth-flow.mmd]
-sequenceDiagram
-    participant U as 用户
-    participant A as 认证服务
-    participant D as 数据库
-    U->>A: 登录请求
-    A->>D: 验证凭证
-    D-->>A: 返回用户信息
-    A-->>U: 返回 Token
-```
-````
+- 以及更多 [Mermaid 支持的图表类型](https://mermaid.js.org/intro())
 
 ## 🛠️ 开发
 

package/app/app.config.ts

@@ -14,11 +14,6 @@ export default defineAppConfig({
     font: 'Public Sans'
   },
   ui: {
-    prose: {
-      codeIcon: {
-        mmd: 'i-vscode-icons-file-type-mermaid'
-      }
-    },
     colors: {
       primary: 'green',
       neutral: 'slate'

package/app/components/content/prose/ProsePre.global.vue

@@ -2,16 +2,23 @@
 import type { ProsePreProps } from '@nuxt/ui'
 // @ts-ignore
 import NuxtUIProsePre from '@nuxt/ui/components/prose/Pre.vue'
-import Mermaid from '../Mermaid.vue'
 
 const props = defineProps<ProsePreProps>()
 
 const isMermaid = computed(() => props.language === 'mermaid')
+
+// 动态解析 Mermaid 组件（仅在 mermaid 模块启用时可用）
+const MermaidComponent = computed(() => {
+  if (!isMermaid.value) return null
+  const resolved = resolveComponent('Mermaid')
+  return typeof resolved === 'string' ? null : resolved
+})
 </script>
 
 <template>
-  <Mermaid
-    v-if="isMermaid"
+  <component
+    :is="MermaidComponent"
+    v-if="isMermaid && MermaidComponent"
     :code="props.code || ''"
     :filename="props.filename"
     :icon="props.icon"

package/modules/mermaid.ts

@@ -0,0 +1,93 @@
+import { createResolver, defineNuxtModule, logger } from '@nuxt/kit'
+
+export interface MermaidModuleOptions {
+  /**
+   * 是否启用 Mermaid 图表支持
+   *
+   * 启用前需安装依赖: `pnpm add mermaid dompurify`
+   * @default false
+   */
+  enabled?: boolean
+}
+
+const log = logger.withTag('movk-nuxt-docs')
+
+export default defineNuxtModule<MermaidModuleOptions>({
+  meta: {
+    name: 'mermaid',
+    configKey: 'mermaid'
+  },
+  defaults: {
+    enabled: false
+  },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
+    const mermaidFilePath = resolve('../app/components/content/Mermaid.vue')
+
+    // Layer 自动扫描会注册 Mermaid.vue，通过 components:extend 统一管理：
+    // - 禁用时：从列表移除，resolveComponent('Mermaid') 返回字符串，ProsePre fallback 到普通代码块
+    // - 启用时：将 mode 改为 'client'，避免 SSR 阶段执行
+    nuxt.hooks.hook('components:extend', (components) => {
+      const idx = components.findIndex(c => c.filePath === mermaidFilePath)
+      if (idx === -1) return
+
+      if (!options.enabled) {
+        components.splice(idx, 1)
+        return
+      }
+
+      components[idx]!.mode = 'client'
+    })
+
+    if (!options.enabled) return
+
+    // 验证 mermaid 依赖是否已安装
+    try {
+      import.meta.resolve('mermaid')
+    } catch {
+      log.warn('[mermaid] `mermaid` package not found. Install it with: pnpm add mermaid dompurify')
+      return
+    }
+
+    // 添加 mermaid 语言高亮
+    const contentOptions = nuxt.options.content as Record<string, any> | false
+    if (contentOptions) {
+      const build = contentOptions.build ??= {}
+      const markdown = build.markdown ??= {}
+      const highlight = markdown.highlight ??= {}
+      const langs = highlight.langs ??= [] as string[]
+      if (!langs.includes('mermaid')) {
+        langs.push('mermaid')
+      }
+    }
+
+    // 为 mermaid ESM 兼容性配置 optimizeDeps
+    nuxt.hooks.hook('vite:extendConfig', (config) => {
+      const cfg = config as { optimizeDeps?: { include?: string[] } }
+      cfg.optimizeDeps ??= {}
+      cfg.optimizeDeps.include ??= []
+      cfg.optimizeDeps.include.push(
+        '@movk/nuxt-docs > mermaid',
+        '@movk/nuxt-docs > mermaid > dayjs',
+        '@movk/nuxt-docs > mermaid > @braintree/sanitize-url',
+        '@movk/nuxt-docs > mermaid > d3',
+        '@movk/nuxt-docs > mermaid > dompurify'
+      )
+    })
+
+    // 注入 mermaid 代码图标配置到 appConfig
+    const appConfig = nuxt.options.appConfig as Record<string, any>
+    appConfig.ui ??= {}
+    appConfig.ui.prose ??= {}
+    appConfig.ui.prose.codeIcon ??= {}
+    appConfig.ui.prose.codeIcon.mmd ??= 'i-vscode-icons-file-type-mermaid'
+
+    log.info('[mermaid] Mermaid diagram support enabled')
+  }
+})
+
+declare module 'nuxt/schema' {
+  interface NuxtConfig {
+    mermaid?: MermaidModuleOptions
+  }
+}

package/nuxt.config.ts

@@ -27,7 +27,7 @@ export default defineNuxtConfig({
     build: {
       markdown: {
         highlight: {
-          langs: ['bash', 'diff', 'json', 'js', 'ts', 'html', 'css', 'vue', 'shell', 'mdc', 'md', 'yaml', 'mermaid']
+          langs: ['bash', 'diff', 'json', 'js', 'ts', 'html', 'css', 'vue', 'shell', 'mdc', 'md', 'yaml']
         },
         remarkPlugins: {
           'remark-mdc': {
@@ -100,13 +100,7 @@ export default defineNuxtConfig({
 
       include.push(
         '@movk/nuxt-docs > @nuxt/content > slugify',
-        '@movk/nuxt-docs > @ai-sdk/gateway > @vercel/oidc',
-        // Fix mermaid ESM compatibility issues
-        '@movk/nuxt-docs > mermaid',
-        '@movk/nuxt-docs > mermaid > dayjs',
-        '@movk/nuxt-docs > mermaid > @braintree/sanitize-url',
-        '@movk/nuxt-docs > mermaid > d3',
-        '@movk/nuxt-docs > mermaid > dompurify'
+        '@movk/nuxt-docs > @ai-sdk/gateway > @vercel/oidc'
       )
     }
   },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@movk/nuxt-docs",
   "type": "module",
-  "version": "1.12.4",
+  "version": "1.13.0",
   "private": false,
   "description": "Modern Nuxt 4 documentation theme with auto-generated component docs, AI chat assistant, MCP server, and complete developer experience optimization.",
   "author": "YiXuan <mhaibaraai@gmail.com>",
@@ -14,9 +14,19 @@
   "main": "./nuxt.config.ts",
   "peerDependencies": {
     "better-sqlite3": "12.x",
+    "dompurify": "3.x",
+    "mermaid": "11.x",
     "nuxt": "4.x",
     "tailwindcss": "4.x"
   },
+  "peerDependenciesMeta": {
+    "dompurify": {
+      "optional": true
+    },
+    "mermaid": {
+      "optional": true
+    }
+  },
   "files": [
     "app",
     "content.config.ts",
@@ -56,10 +66,8 @@
     "@vueuse/nuxt": "^14.2.1",
     "ai": "^6.0.99",
     "defu": "^6.1.4",
-    "dompurify": "^3.3.1",
     "exsolve": "^1.0.8",
     "git-url-parse": "^16.1.0",
-    "mermaid": "^11.12.3",
     "minimark": "^1.0.0",
     "motion-v": "^2.0.0",
     "nuxt": "^4.3.1",