@movk/nuxt-docs 1.15.0 → 1.16.1

package/README.md

@@ -1,3 +1,4 @@
+[![Movk Nuxt Docs OG](https://docs.mhaibaraai.cn/_og/s/c_Docs,title_~546w5Luj5YyWIE51eHQg5paH5qGj5Li76aKY,description_~5Z-65LqOIE51eHQgNCDnmoTnjrDku6PmlofmoaPkuLvpopjvvIzpm4bmiJDnu4Tku7boh6rliqjljJbmlofmoaPjgIFBSSDogYrlpKnliqnmiYvjgIFNQ1AgU2VydmVyIOWSjOWujOaVtOeahOW8gOWPkeiAheS9k-mqjOS8mOWMluOAgg.png)](https://docs.mhaibaraai.cn/)
 [![Movk Nuxt Docs](https://docs.mhaibaraai.cn/og-image.png)](https://docs.mhaibaraai.cn/)
 
 > 基于 Nuxt 4 的现代文档主题，集成组件自动化文档、AI 聊天助手、MCP Server 和完整的开发者体验优化
@@ -21,7 +22,7 @@
 ### 🤖 AI 增强体验
 
 <div style="padding: 40px 0; display: flex; justify-content: center;">
-  <img src="https://docs.mhaibaraai.cn/ai/AiChat.png" alt="AiChat" width="400">
+<img src="https://docs.mhaibaraai.cn/ai/AiChat.png" alt="AiChat" width="400">
 </div>
 
 - **AI 聊天助手** - 内置智能文档助手，基于 Vercel AI SDK 支持多种 LLM 模型
@@ -189,7 +190,10 @@ pnpm add mermaid dompurify
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   extends: ['@movk/nuxt-docs'],
-  mermaid: { enabled: true }
+
+  movkNuxtDocs: {
+    mermaid: true
+  }
 })
 ```
 
@@ -198,11 +202,11 @@ export default defineNuxtConfig({
 ````md [md]
 ```mermaid
 graph TD
-    A[开始] --> B{是否有效?}
-    B -->|是| C[处理数据]
-    B -->|否| D[显示错误]
-    C --> E[完成]
-    D --> E
+A[开始] --> B{是否有效?}
+B -->|是| C[处理数据]
+B -->|否| D[显示错误]
+C --> E[完成]
+D --> E
 ```
 ````
 
@@ -215,9 +219,9 @@ graph TD
 
 **支持的图表类型：**
 - **流程图**（`flowchart`/`graph`）：用于展示流程和决策
-  ![Mermaid 流程图示例](https://docs.mhaibaraai.cn/mermaid/mermaid-flowchart.png)
+![Mermaid 流程图示例](https://docs.mhaibaraai.cn/mermaid/mermaid-flowchart.png)
 - **时序图**（`sequenceDiagram`）：用于展示交互时序
-  ![Mermaid 时序图示例](https://docs.mhaibaraai.cn/mermaid/mermaid-sequence.png)
+![Mermaid 时序图示例](https://docs.mhaibaraai.cn/mermaid/mermaid-sequence.png)
 - **类图**（`classDiagram`）：用于展示类关系
 - **状态图**（`stateDiagram`）：用于展示状态转换
 - **甘特图**（`gantt`）：用于展示项目时间线
@@ -225,6 +229,20 @@ graph TD
 - **Git 图**（`gitGraph`）：用于展示分支历史
 - 以及更多 [Mermaid 支持的图表类型](https://mermaid.js.org/intro())
 
+### 无障碍支持（A11y）
+
+Movk Nuxt Docs 默认启用 `@nuxt/a11y`。如需关闭，可在 `movkNuxtDocs` 中设置：
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  extends: ['@movk/nuxt-docs'],
+
+  movkNuxtDocs: {
+    a11y: false
+  }
+})
+```
+
 ## 🛠️ 开发
 
 ### 本地开发

package/app/components/OgImage/OgImageDocs.takumi.vue

@@ -11,10 +11,7 @@ withDefaults(defineProps<{
 </script>
 
 <template>
-  <div
-    style="font-family: 'Public Sans', 'Noto Sans SC', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;"
-    class="w-full h-full flex flex-col justify-center items-center relative p-10 lg:p-15 bg-white text-neutral-900 dark:bg-neutral-900 dark:text-neutral-50"
-  >
+  <div style="font-family: 'Noto Sans SC', sans-serif;" class="w-full h-full flex flex-col justify-center items-center relative p-10 lg:p-15 bg-white text-neutral-900 dark:bg-neutral-900 dark:text-neutral-50">
     <div
       class="absolute top-0 left-0 right-0 bottom-0"
       :style="{
@@ -82,7 +79,10 @@ withDefaults(defineProps<{
         </h1>
       </div>
 
-      <p v-if="description" class="text-slate-500 text-[24px] lg:text-[32px] opacity-70 max-w-162.5 lg:max-w-225 leading-normal">
+      <p
+        v-if="description"
+        class="text-slate-500 text-[24px] lg:text-[32px] opacity-70 max-w-162.5 lg:max-w-225 leading-normal"
+      >
         {{ description }}
       </p>
     </div>

package/modules/ai-chat/runtime/components/AiChatPanel.vue

@@ -98,8 +98,11 @@ function getToolIcon(part: ToolPart): string {
   const { toolIcon } = useToolCall(part.state, toolName, part.input || {} as any)
 
   const iconMap: Record<string, string> = {
-    'get-page': 'i-lucide-file-text',
-    'get-example': 'i-lucide-file-text',
+    'get-page': 'i-lucide-book-open',
+    'get-example': 'i-lucide-codepen',
+    'list-examples': 'i-lucide-codesandbox',
+    'list-getting-started-guides': 'i-lucide-square-play',
+    'list-pages': 'i-lucide-book-minus',
     ...toolIcon
   }
 

package/modules/config.ts

@@ -1,27 +1,9 @@
-import { existsSync } from 'node:fs'
 import { createResolver, defineNuxtModule } from '@nuxt/kit'
 import { defu } from 'defu'
-import { join } from 'pathe'
 import { getGitBranch, getGitEnv, getLocalGitInfo } from '../utils/git'
 import { getPackageJsonMetadata, inferSiteURL } from '../utils/meta'
 import { createComponentMetaExcludeFilters } from '../utils/component-meta'
 
-function getMdcConfigSources(nuxt: any): string[] {
-  return nuxt.options._layers.flatMap((layer: any) => {
-    const tsConfigPath = join(layer.config.srcDir, 'mdc.config.ts')
-    if (existsSync(tsConfigPath)) {
-      return [tsConfigPath]
-    }
-
-    const jsConfigPath = join(layer.config.srcDir, 'mdc.config.js')
-    if (existsSync(jsConfigPath)) {
-      return [jsConfigPath]
-    }
-
-    return []
-  })
-}
-
 export default defineNuxtModule({
   meta: {
     name: 'config'
@@ -91,10 +73,12 @@ export default defineNuxtModule({
       ]
     })
 
-    // Load mdc.config from all layers
-    const mdcConfigSources = getMdcConfigSources(nuxt)
-    if (mdcConfigSources.length > 0) {
-      await nuxt.callHook('mdc:configSources', mdcConfigSources)
-    }
+    nuxt.hook('nitro:config', (nitroConfig) => {
+      nitroConfig.publicAssets ||= []
+      nitroConfig.publicAssets.push({
+        dir: resolve('./runtime/public'),
+        maxAge: 60 * 60 * 24 * 30
+      })
+    })
   }
 })

package/modules/module.ts

@@ -0,0 +1,103 @@
+import { addComponentsDir, createResolver, defineNuxtModule, logger } from '@nuxt/kit'
+import type { ModuleDependencies } from 'nuxt/schema'
+
+export interface ModuleOptions {
+  /**
+   * 是否启用 @nuxt/a11y 无障碍支持
+   * @defaultValue true
+   * @see https://a11y.nuxtjs.org/
+   */
+  a11y?: boolean
+  /**
+   * 是否启用 Mermaid 图表支持
+   * - 启用前需安装依赖: `pnpm add mermaid dompurify`
+   * @defaultValue false
+   */
+  mermaid?: boolean
+}
+
+const log = logger.withTag('movk-nuxt-docs')
+
+export default defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: 'movk-nuxt-docs',
+    configKey: 'movkNuxtDocs'
+  },
+  defaults: {
+    a11y: true,
+    mermaid: false
+  },
+  moduleDependencies(nuxt): ModuleDependencies {
+    const userOptions = nuxt.options.movkNuxtDocs || {}
+    return {
+      ...userOptions.a11y !== false && {
+        '@nuxt/a11y': {
+          version: '^1.0.0-alpha.1'
+        }
+      }
+    }
+  },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
+
+    if (options.mermaid) {
+      let mermaidAvailable = true
+      try {
+        import.meta.resolve('mermaid')
+      } catch {
+        log.warn('mermaid package not found. install it with: pnpm add mermaid dompurify')
+        mermaidAvailable = false
+      }
+
+      if (mermaidAvailable) {
+        addComponentsDir({
+          path: resolve('./runtime/components/prose'),
+          pathPrefix: false,
+          prefix: 'Prose',
+          global: true
+        })
+
+        // 添加 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 diagram support enabled')
+      }
+    }
+  }
+})
+
+declare module 'nuxt/schema' {
+  interface NuxtConfig {
+    movkNuxtDocs?: ModuleOptions
+  }
+}

package/{app/components/content/prose/ProsePre.global.vue → modules/runtime/components/prose/Pre.vue}

@@ -1,16 +1,13 @@
 <script setup lang="ts">
 import type { ProsePreProps } from '@nuxt/ui'
-// @ts-ignore
+// @ts-ignore - #build alias only available at Nuxt build time
 import NuxtUIProsePre from '@nuxt/ui/components/prose/Pre.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')
+  if (props.language !== 'mermaid') return null
+  const resolved = resolveComponent('ProseMermaid')
   return typeof resolved === 'string' ? null : resolved
 })
 </script>
@@ -18,11 +15,12 @@ const MermaidComponent = computed(() => {
 <template>
   <component
     :is="MermaidComponent"
-    v-if="isMermaid && MermaidComponent"
+    v-if="MermaidComponent"
     :code="props.code || ''"
     :filename="props.filename"
     :icon="props.icon"
   />
+
   <NuxtUIProsePre v-else v-bind="props">
     <slot />
   </NuxtUIProsePre>

package/nuxt.config.ts

@@ -20,7 +20,6 @@ export default defineNuxtConfig({
     '@nuxt/fonts',
     '@nuxt/content',
     '@nuxt/image',
-    '@nuxt/a11y',
     '@nuxtjs/robots',
     '@nuxtjs/mcp-toolkit',
     '@vueuse/nuxt',
@@ -172,10 +171,9 @@ export default defineNuxtConfig({
   },
 
   fonts: {
-    provider: 'bunny',
     families: [
-      { name: 'Public Sans', global: true, fallbacks: ['Noto Sans SC', 'sans-serif'] },
-      { name: 'Noto Sans SC', global: true }
+      { name: 'Public Sans', global: true },
+      { name: 'Noto Sans SC', global: true, provider: 'local' }
     ]
   },
 
@@ -196,5 +194,9 @@ export default defineNuxtConfig({
     // Must be defined before @nuxt/content setup,
     // otherwise Content LLMS module will overwrite it in modules:done.
     contentRawMarkdown: false
+  },
+
+  ogImage: {
+    zeroRuntime: true
   }
 })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@movk/nuxt-docs",
   "type": "module",
-  "version": "1.15.0",
+  "version": "1.16.1",
   "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>",
@@ -39,10 +39,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@ai-sdk/gateway": "^3.0.79",
+    "@ai-sdk/gateway": "^3.0.83",
     "@ai-sdk/mcp": "^1.0.30",
-    "@ai-sdk/vue": "^3.0.137",
-    "@iconify-json/lucide": "^1.2.98",
+    "@ai-sdk/vue": "^3.0.141",
+    "@iconify-json/lucide": "^1.2.100",
     "@iconify-json/simple-icons": "^1.2.75",
     "@iconify-json/vscode-icons": "^1.2.45",
     "@movk/core": "^1.2.2",
@@ -52,8 +52,8 @@
     "@nuxt/kit": "^4.4.2",
     "@nuxt/ui": "^4.6.0",
     "@nuxtjs/mcp-toolkit": "^0.12.0",
-    "@nuxtjs/mdc": "^0.20.2",
-    "@nuxtjs/robots": "^5.7.1",
+    "@nuxtjs/mdc": "^0.21.0",
+    "@nuxtjs/robots": "^6.0.6",
     "@octokit/rest": "^22.0.1",
     "@shikijs/core": "^4.0.2",
     "@shikijs/engine-javascript": "^4.0.2",
@@ -63,14 +63,14 @@
     "@takumi-rs/wasm": "^0.73.1",
     "@vueuse/core": "^14.2.1",
     "@vueuse/nuxt": "^14.2.1",
-    "ai": "^6.0.137",
+    "ai": "^6.0.141",
     "defu": "^6.1.4",
     "exsolve": "^1.0.8",
     "git-url-parse": "^16.1.0",
     "motion-v": "^2.2.0",
     "nuxt-component-meta": "^0.17.2",
     "nuxt-llms": "^0.2.0",
-    "nuxt-og-image": "^6.1.2",
+    "nuxt-og-image": "^6.3.0",
     "ohash": "^2.0.11",
     "pathe": "^2.0.3",
     "pkg-types": "^2.3.0",

package/server/mcp/tools/get-example.ts

@@ -13,7 +13,7 @@ export default defineMcpTool({
         content: [{ type: 'text' as const, text: result.code }]
       }
     } catch {
-      return errorResult(`示例 '${exampleName}' 未找到。使用 list_examples 工具查看所有可用示例。`)
+      throw createError({ statusCode: 404, message: `示例 '${exampleName}' 未找到。使用 list_examples 工具查看所有可用示例。` })
     }
   }
 })

package/server/mcp/tools/get-page.ts

@@ -22,7 +22,7 @@ export default defineMcpTool({
         content: [{ type: 'text', text: JSON.stringify(content, null, 2) }]
       }
     } catch (error) {
-      return errorResult(`获取页面失败: ${error}`)
+      throw createError({ statusCode: 500, message: `获取页面失败: ${error}` })
     }
   }
 })

package/server/mcp/tools/list-examples.ts

@@ -5,6 +5,6 @@ export default defineMcpTool({
   description: '列出所有可用的示例和代码演示',
   cache: '1h',
   async handler() {
-    return jsonResult(await listComponentExamples())
+    return await listComponentExamples()
   }
 })

package/server/mcp/tools/list-getting-started-guides.ts

@@ -22,6 +22,6 @@ export default defineMcpTool({
       navigation: page.navigation
     })).sort((a, b) => a.path.localeCompare(b.path))
 
-    return jsonResult(result)
+    return result
   }
 })

package/server/mcp/tools/list-pages.ts

@@ -8,10 +8,10 @@ export default defineMcpTool({
 
     const pages = await queryCollection(event, 'docs').all()
 
-    return jsonResult(pages.map(doc => ({
+    return pages.map(doc => ({
       title: doc.title,
       description: doc.description,
       path: doc.path
-    })))
+    }))
   }
 })

package/utils/component-meta.ts

@@ -52,11 +52,7 @@ export function createComponentMetaExcludeFilters(
     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'),
-    resolve('./ai-chat/runtime/components/AiChatPreStream.vue')
+    resolve('./runtime/components/prose/Mermaid.vue')
   ]
 
   const userComponentPaths = [

package/modules/mermaid.ts

@@ -1,93 +0,0 @@
-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
-  }
-}