@movk/nuxt-docs 1.7.5 → 1.8.0

package/README.md

@@ -37,6 +37,7 @@
 - ⚡ **基于 Nuxt 4** - 充分利用最新的 Nuxt 框架，实现卓越性能
 - 🎨 **采用 Nuxt UI** - 集成全面的 UI 组件库，开箱即用
 - 📝 **MDC 语法增强** - 支持 Markdown 与 Vue 组件的无缝集成
+- 📊 **Mermaid 图表** - 内置 Mermaid 支持，渲染流程图、时序图、类图等可视化图表，支持自动主题切换和全屏查看
 - 🔍 **全文搜索** - 基于 Nuxt Content 的 `ContentSearch` 组件，支持键盘快捷键（⌘K）
 - 🌙 **暗黑模式** - 支持亮色/暗色主题切换
 - 📱 **响应式设计** - 移动优先的响应式布局
@@ -183,6 +184,55 @@ icon: i-lucide-rocket
 
 了解更多关于 MDC 语法，请查看 [Nuxt Content 文档](https://content.nuxt.com/docs/files/markdown#mdc-syntax)。
 
+### Mermaid 图表
+
+使用 ` ```mermaid ` 代码块渲染可视化图表，支持流程图、时序图、类图等多种图表类型：
+
+````md [md]
+```mermaid
+graph TD
+    A[开始] --> B{是否有效?}
+    B -->|是| C[处理数据]
+    B -->|否| D[显示错误]
+    C --> E[完成]
+    D --> E
+```
+````
+
+**主要特性：**
+- 🎨 自动主题切换（深色/浅色模式）
+- 🔄 懒加载（仅在可见时渲染）
+- 📋 一键复制图表代码
+- 🖼️ 全屏查看功能
+- 🔒 安全渲染（DOMPurify 清理）
+
+**支持的图表类型：**
+- **流程图**（`flowchart`/`graph`）：用于展示流程和决策
+  ![Mermaid 流程图示例](https://docs.mhaibaraai.cn/mermaid/mermaid-flowchart.png)
+- **时序图**（`sequenceDiagram`）：用于展示交互时序
+  ![Mermaid 时序图示例](https://docs.mhaibaraai.cn/mermaid/mermaid-sequence.png)
+- **类图**（`classDiagram`）：用于展示类关系
+- **状态图**（`stateDiagram`）：用于展示状态转换
+- **甘特图**（`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
+```
+````
+
 ## 🛠️ 开发
 
 ### 本地开发

package/app/app.config.ts

@@ -14,6 +14,11 @@ 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/Mermaid.vue

@@ -0,0 +1,199 @@
+<script setup lang="ts">
+import { hash } from 'ohash'
+import type { IconProps } from '@nuxt/ui'
+import type { ClassNameValue } from 'tailwind-merge'
+import {
+  useClipboard,
+  useElementVisibility,
+  useEventListener,
+  useToggle
+} from '@vueuse/core'
+import { tv } from '@nuxt/ui/utils/tv'
+
+const theme = {
+  slots: {
+    root: 'relative my-5 group border border-muted rounded-md overflow-hidden',
+    header: 'flex items-center gap-1.5 border-b border-muted bg-default px-4 py-3',
+    filename: 'text-default text-sm/6',
+    icon: 'size-4 shrink-0',
+    toolbar: 'absolute top-2 right-2 flex gap-1 z-10 opacity-0 group-hover:opacity-100 transition-opacity',
+    diagram: 'p-4 flex justify-center bg-elevated overflow-x-auto',
+    loading: 'p-4 flex items-center justify-center gap-2 text-sm text-muted',
+    error: 'p-4 flex items-center justify-center gap-2 text-sm text-error bg-error/10'
+  },
+  variants: {
+    fullscreen: {
+      true: {
+        root: 'fixed inset-0 z-50 m-0 rounded-none bg-default flex flex-col',
+        diagram: 'flex-1 overflow-auto',
+        toolbar: 'opacity-100'
+      }
+    },
+    filename: {
+      true: {
+        root: ''
+      }
+    }
+  }
+}
+
+export interface MermaidProps {
+  /** 图表代码 */
+  code: string
+  /**
+   * 图标
+   * @IconifyIcon
+   */
+  icon?: IconProps['name']
+  /** 文件名 */
+  filename?: string
+  class?: ClassNameValue
+  ui?: Partial<typeof theme.slots>
+}
+
+export interface MermaidSlots {
+  default?(props: {}): any
+}
+
+const props = defineProps<MermaidProps>()
+
+defineSlots<MermaidSlots>()
+
+const appConfig = useAppConfig() as { ui?: { icons?: { copy?: string, copyCheck?: string }, prose?: { mermaid?: typeof theme } } }
+const colorMode = useColorMode()
+
+const ui = computed(() => tv({
+  extend: tv(theme),
+  ...(appConfig.ui?.prose?.mermaid || {})
+})({
+  fullscreen: isFullscreen.value,
+  filename: !!props.filename
+}))
+
+const copyIcon = computed(() => appConfig.ui?.icons?.copy || 'i-lucide-copy')
+const copyCheckIcon = computed(() => appConfig.ui?.icons?.copyCheck || 'i-lucide-check')
+
+const mermaidId = computed(() => `mermaid-${hash(props.code)}`)
+const mermaidTheme = computed(() => colorMode.value === 'dark' ? 'dark' : 'default')
+
+const containerRef = ref<HTMLElement | null>(null)
+const diagramRef = ref<HTMLElement | null>(null)
+const isRendered = ref(false)
+const hasError = ref(false)
+const errorMessage = ref('')
+
+const [isFullscreen, toggleFullscreen] = useToggle(false)
+const { copy, copied } = useClipboard({ source: () => props.code })
+const isVisible = useElementVisibility(containerRef)
+
+async function renderMermaid() {
+  if (!props.code || isRendered.value || !diagramRef.value) return
+
+  try {
+    // 动态导入 mermaid 和 dompurify，仅在客户端执行
+    const [mermaid, DOMPurify] = await Promise.all([
+      import('mermaid').then(m => m.default),
+      import('dompurify').then(m => m.default)
+    ])
+    mermaid.initialize({
+      startOnLoad: false,
+      theme: mermaidTheme.value,
+      securityLevel: 'strict',
+      fontFamily: 'inherit'
+    })
+
+    const { svg } = await mermaid.render(mermaidId.value, props.code)
+    const sanitized = DOMPurify.sanitize(svg, {
+      USE_PROFILES: { svg: true, svgFilters: true },
+      ADD_TAGS: ['foreignObject']
+    })
+    diagramRef.value.innerHTML = sanitized
+    isRendered.value = true
+  } catch (e) {
+    hasError.value = true
+    errorMessage.value = e instanceof Error ? e.message : 'Mermaid render failed'
+    console.error('[Mermaid]', errorMessage.value)
+  }
+}
+
+async function reRender() {
+  if (!diagramRef.value) return
+  isRendered.value = false
+  hasError.value = false
+  diagramRef.value.innerHTML = ''
+  await renderMermaid()
+}
+
+watch(
+  [isVisible, diagramRef],
+  ([visible, el]) => {
+    if (visible && el && !isRendered.value) {
+      renderMermaid()
+    }
+  },
+  { immediate: true }
+)
+
+watch(mermaidTheme, () => {
+  if (isRendered.value) reRender()
+})
+
+watch(() => props.code, () => {
+  if (isVisible.value) reRender()
+})
+
+useEventListener('keydown', (e: KeyboardEvent) => {
+  if (e.key === 'Escape' && isFullscreen.value) {
+    isFullscreen.value = false
+  }
+})
+</script>
+
+<template>
+  <div ref="containerRef" :class="ui.root({ class: [props.ui?.root, props.class] })">
+    <div v-if="filename" :class="ui.header({ class: props.ui?.header })">
+      <UIcon v-if="icon" :name="icon" :class="ui.icon({ class: props.ui?.icon })" />
+      <ProseCodeIcon v-else :filename="filename" :class="ui.icon({ class: props.ui?.icon })" />
+      <span :class="ui.filename({ class: props.ui?.filename })">{{ filename }}</span>
+    </div>
+
+    <div v-if="isRendered" :class="ui.toolbar({ class: props.ui?.toolbar })">
+      <UButton
+        :icon="copied ? copyCheckIcon : copyIcon"
+        color="neutral"
+        variant="ghost"
+        size="xs"
+        :aria-label="copied ? 'Copied' : 'Copy code'"
+        @click="copy()"
+      />
+      <UButton
+        :icon="isFullscreen ? 'i-lucide-minimize-2' : 'i-lucide-maximize-2'"
+        color="neutral"
+        variant="ghost"
+        size="xs"
+        :aria-label="isFullscreen ? 'Exit fullscreen' : 'Fullscreen'"
+        @click="toggleFullscreen()"
+      />
+    </div>
+
+    <div v-if="hasError" :class="ui.error({ class: props.ui?.error })">
+      <UIcon name="i-lucide-alert-triangle" class="size-4" />
+      <span>{{ errorMessage }}</span>
+    </div>
+
+    <template v-else>
+      <div v-if="!isRendered" :class="ui.loading({ class: props.ui?.loading })">
+        <UIcon name="i-lucide-loader-2" class="size-4 animate-spin" />
+        <span>Loading diagram...</span>
+      </div>
+      <div v-show="isRendered" ref="diagramRef" :class="ui.diagram({ class: props.ui?.diagram })" />
+    </template>
+  </div>
+</template>
+
+<style>
+[class*="diagram"] :deep(svg) {
+  max-width: 100%;
+  height: auto;
+}
+</style>

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

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+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')
+</script>
+
+<template>
+  <Mermaid
+    v-if="isMermaid"
+    :code="props.code || ''"
+    :filename="props.filename"
+    :icon="props.icon"
+  />
+  <NuxtUIProsePre v-else v-bind="props">
+    <slot />
+  </NuxtUIProsePre>
+</template>

package/modules/config.ts

@@ -66,6 +66,7 @@ export default defineNuxtModule({
       resolve('../app/components/content/ComponentProps.vue'),
       resolve('../app/components/content/ComponentSlots.vue'),
       resolve('../app/components/content/PageLastCommit.vue'),
+      resolve('../app/components/content/Mermaid.vue'),
       resolve('./ai-chat/runtime/components/AiChatToolCall.vue'),
       resolve('./ai-chat/runtime/components/AiChatReasoning.vue'),
       resolve('./ai-chat/runtime/components/AiChatSlideoverFaq.vue'),
@@ -78,7 +79,7 @@ export default defineNuxtModule({
       join(dir, 'templates/*/app/components')
     ]
 
-    // @ts-ignore - component-meta 的类型定义在运行时才能正确解析
+    // @ts-ignore - component-meta is not typed
     nuxt.hook('component-meta:extend', (options: any) => {
       options.exclude = [
         ...(options.exclude || []),

package/nuxt.config.ts

@@ -24,7 +24,9 @@ export default defineNuxtConfig({
         config.optimizeDeps.include.push(
           '@nuxt/content > slugify',
           'extend',
-          '@ai-sdk/gateway > @vercel/oidc'
+          '@ai-sdk/gateway > @vercel/oidc',
+          'mermaid',
+          'dompurify'
         )
         config.optimizeDeps.include = config.optimizeDeps.include
           .map(id => id.replace(/^@nuxt\/content > /, '@movk/nuxt-docs > @nuxt/content > '))
@@ -42,7 +44,7 @@ export default defineNuxtConfig({
     build: {
       markdown: {
         highlight: {
-          langs: ['bash', 'diff', 'json', 'js', 'ts', 'html', 'css', 'vue', 'shell', 'mdc', 'md', 'yaml']
+          langs: ['bash', 'diff', 'json', 'js', 'ts', 'html', 'css', 'vue', 'shell', 'mdc', 'md', 'yaml', 'mermaid']
         },
         remarkPlugins: {
           'remark-mdc': {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@movk/nuxt-docs",
   "type": "module",
-  "version": "1.7.5",
+  "version": "1.8.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>",
@@ -28,13 +28,13 @@
     "README.md"
   ],
   "dependencies": {
-    "@ai-sdk/gateway": "^3.0.16",
-    "@ai-sdk/mcp": "^1.0.10",
-    "@ai-sdk/vue": "^3.0.41",
+    "@ai-sdk/gateway": "^3.0.17",
+    "@ai-sdk/mcp": "^1.0.11",
+    "@ai-sdk/vue": "^3.0.42",
     "@iconify-json/lucide": "^1.2.86",
     "@iconify-json/ph": "^1.2.2",
-    "@iconify-json/tabler": "^1.2.26",
     "@iconify-json/simple-icons": "^1.2.67",
+    "@iconify-json/tabler": "^1.2.26",
     "@iconify-json/vscode-icons": "^1.2.40",
     "@movk/core": "^1.1.0",
     "@nuxt/a11y": "^1.0.0-alpha.1",
@@ -45,15 +45,17 @@
     "@nuxtjs/mcp-toolkit": "^0.6.2",
     "@nuxtjs/seo": "^3.3.0",
     "@octokit/rest": "^22.0.1",
-    "@openrouter/ai-sdk-provider": "^1.5.4",
+    "@openrouter/ai-sdk-provider": "^2.0.0",
     "@vercel/analytics": "^1.6.1",
     "@vercel/speed-insights": "^1.3.1",
     "@vueuse/core": "^14.1.0",
     "@vueuse/nuxt": "^14.1.0",
-    "ai": "^6.0.41",
+    "ai": "^6.0.42",
     "defu": "^6.1.4",
+    "dompurify": "^3.2.6",
     "exsolve": "^1.0.8",
     "git-url-parse": "^16.1.0",
+    "mermaid": "^11.12.2",
     "motion-v": "^1.9.0",
     "nuxt": "^4.2.2",
     "nuxt-component-meta": "^0.17.1",