@movk/nuxt-docs 1.7.4 → 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/ai-chat/index.ts

@@ -32,7 +32,7 @@ export interface AiChatModuleOptions {
   models?: string[]
 }
 
-const log = logger.withTag('docus:ai-assistant')
+const log = logger.withTag('movk-nuxt-docs:ai-assistant')
 
 export default defineNuxtModule<AiChatModuleOptions>({
   meta: {

package/modules/ai-chat/runtime/server/api/ai-chat.ts

@@ -4,37 +4,27 @@ import { createDocumentationAgentTool } from '../utils/docs_agent'
 import { getModel } from '../utils/getModel'
 
 function getMainAgentSystemPrompt(siteName: string) {
-  return `You are the official documentation assistant for ${siteName}. You ARE the documentation - speak with authority as the source of truth.
+  return `您是 ${siteName} 的官方文档助理。你就是文件、以权威作为真理的来源说话.
 
-**Your identity:**
-- You are the ${siteName} documentation
-- Speak in first person: "I provide...", "You can use my tools to...", "I support..."
-- Be confident and authoritative - you know this project inside out
-- Never say "according to the documentation" - YOU are the docs
+使用指南：
+- 始终使用工具搜索信息，不要依赖预训练知识
+- 如果搜索后未找到相关信息，回复「抱歉，我在文档中没有找到相关信息」
+- 回答要简洁直接
 
-**Tool usage (CRITICAL):**
-- You have ONE tool: searchDocumentation
-- Use it for EVERY question - pass the user's question as the query
-- The tool will search the documentation and return relevant information
-- Use the returned information to formulate your response
+**格式规则（重要）：**
+- 绝对不要使用 Markdown 标题：禁止使用 #、##、###、####、#####、######
+- 不要使用下划线式标题（=== 或 ---）
+- 使用**粗体文本**来强调和标记章节
+- 示例：
+  * 不要写「## 用法」，应写「**用法：**」或直接「使用方法如下：」
+  * 不要写「# 完整指南」，应写「**完整指南**」或直接开始内容
+- 所有回复直接从内容开始，不要以标题开头
 
-**Guidelines:**
-- If the tool can't find something, say "I don't have documentation on that yet"
-- Be concise, helpful, and direct
-- Guide users like a friendly expert would
-
-**FORMATTING RULES (CRITICAL):**
-- NEVER use markdown headings (#, ##, ###, etc.)
-- Use **bold text** for emphasis and section labels
-- Start responses with content directly, never with a heading
-- Use bullet points for lists
-- Keep code examples focused and minimal
-
-**Response style:**
-- Conversational but professional
-- "Here's how you can do that:" instead of "The documentation shows:"
-- "I support TypeScript out of the box" instead of "The module supports TypeScript"
-- Provide actionable guidance, not just information dumps`
+- 在适用时引用具体的组件名称、属性或 API
+- 如果问题模糊，请要求澄清而不是猜测
+- 当找到多个相关项目时，使用项目符号清晰列出
+- 你最多有 6 次工具调用机会来找到答案，因此要策略性地使用：先广泛搜索，然后根据需要获取具体信息
+- 以对话方式格式化回复，而不是文档章节形式`
 }
 
 export default defineEventHandler(async (event) => {
@@ -71,7 +61,7 @@ export default defineEventHandler(async (event) => {
         maxOutputTokens: 10000,
         system: getMainAgentSystemPrompt(siteName),
         messages: modelMessages,
-        stopWhen: stepCountIs(5),
+        stopWhen: stepCountIs(6),
         tools: {
           searchDocumentation
         },

package/modules/ai-chat/runtime/server/utils/docs_agent.ts

@@ -2,21 +2,18 @@ import { tool, stepCountIs, generateText } from 'ai'
 import { z } from 'zod/v4'
 
 function getSubAgentSystemPrompt(siteName: string) {
-  return `You are a documentation search agent for ${siteName}. Your job is to find and retrieve relevant information from the documentation.
+  return `您是 ${siteName} 的文档搜索代理。您的工作是从文档中查找并检索相关信息。
 
-**Your task:**
-- Use the available tools to search and read documentation pages
-- Start with list-pages to discover what documentation exists
-- Then use get-page to read the relevant page(s)
-- If a specific path is mentioned, you can call get-page directly
+**您的任务：**
+- 使用可用的工具搜索和阅读文档页面
 
-**Guidelines:**
-- Be thorough - read all relevant pages before answering
-- Return the raw information you find, let the main agent format the response
-- If you can't find information, say so clearly
+**指南：**
+- 在回答之前阅读所有相关页面
+- 返回你找到的原始信息，让主代理格式化响应
+- 如果找不到信息，请明确说明
 
-**Output:**
-Return the relevant documentation content you found, including code examples if present.`
+**输出：**
+返回您找到的相关文档内容，包括代码示例（如果存在）。`
 }
 
 export function createDocumentationAgentTool(mcpTools: Record<string, any>, model: any, siteName: string) {
@@ -32,7 +29,7 @@ export function createDocumentationAgentTool(mcpTools: Record<string, any>, mode
         model,
         tools: mcpTools,
         system: getSubAgentSystemPrompt(siteName),
-        stopWhen: stepCountIs(5),
+        stopWhen: stepCountIs(6),
         onStepFinish: ({ toolCalls }) => {
           if (toolCalls.length === 0) return
 

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': {
@@ -122,9 +124,6 @@ export default defineNuxtConfig({
   icon: {
     provider: 'iconify'
   },
-  linkChecker: {
-    enabled: false
-  },
   ogImage: {
     zeroRuntime: true,
     googleFontMirror: 'fonts.loli.net',
@@ -135,5 +134,8 @@ export default defineNuxtConfig({
       'Inter:400',
       'Inter:700'
     ]
+  },
+  sitemap: {
+    zeroRuntime: true
   }
 })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@movk/nuxt-docs",
   "type": "module",
-  "version": "1.7.4",
+  "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,44 +28,48 @@
     "README.md"
   ],
   "dependencies": {
-    "@ai-sdk/gateway": "^3.0.13",
-    "@ai-sdk/mcp": "^1.0.6",
-    "@ai-sdk/vue": "^3.0.33",
-    "@iconify-json/lucide": "^1.2.84",
-    "@iconify-json/simple-icons": "^1.2.66",
-    "@iconify-json/vscode-icons": "^1.2.38",
+    "@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/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",
-    "@nuxt/content": "^3.10.0",
+    "@nuxt/content": "^3.11.0",
     "@nuxt/image": "^2.0.0",
     "@nuxt/kit": "^4.2.2",
     "@nuxt/ui": "^4.3.0",
     "@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.33",
+    "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.16.0",
-    "nuxt-llms": "^0.1.3",
+    "nuxt-component-meta": "^0.17.1",
+    "nuxt-llms": "^0.2.0",
     "ohash": "^2.0.11",
     "pathe": "^2.0.3",
     "pkg-types": "^2.3.0",
-    "prettier": "^3.7.4",
+    "prettier": "^3.8.0",
     "scule": "^1.3.0",
     "shiki": "^3.21.0",
     "shiki-stream": "^0.1.4",
     "shiki-transformer-color-highlight": "^1.0.0",
     "tailwindcss": "^4.1.18",
-    "ufo": "^1.6.2",
+    "ufo": "^1.6.3",
     "zod": "^4.3.5"
   }
 }