@movk/nuxt-docs 1.17.4 → 1.17.6

package/app/components/PageHeaderLinks.vue

@@ -10,6 +10,7 @@ const { ui } = useAppConfig()
 const appBaseURL = useRuntimeConfig().app?.baseURL || '/'
 
 const mdPath = computed(() => `${site.url}/raw${route.path}.md`)
+const aiPrompt = computed(() => `I'm looking at this documentation: ${mdPath.value}\nHelp me understand how to use it. Be ready to explain concepts, give examples, or help debug based on it.`)
 
 const items = [[
   {
@@ -33,13 +34,13 @@ const items = [[
     label: 'Open in ChatGPT',
     icon: 'i-simple-icons-openai',
     target: '_blank',
-    to: `https://chatgpt.com/?hints=search&q=${encodeURIComponent(`Read ${mdPath.value} so I can ask questions about it.`)}`
+    to: `https://chatgpt.com/?prompt=${encodeURIComponent(aiPrompt.value)}`
   },
   {
     label: 'Open in Claude',
     icon: 'i-simple-icons-anthropic',
     target: '_blank',
-    to: `https://claude.ai/new?q=${encodeURIComponent(`Read ${mdPath.value} so I can ask questions about it.`)}`
+    to: `https://claude.ai/new?q=${encodeURIComponent(aiPrompt.value)}`
   }
 ], [
   {

package/nuxt.config.ts

@@ -167,12 +167,14 @@ export default defineNuxtConfig({
     ]
   },
 
+  // for users in China who may have trouble loading Google Fonts.
   fonts: {
+    provider: 'alibaba-puhuiti',
     providers: {
-      'alibaba-puhuiti': createAlibabaPuHuiTiProvider('https://cdn.mhaibaraai.cn/fonts')
+      'alibaba-puhuiti': createAlibabaPuHuiTiProvider('https://cdn.mhaibaraai.cn/fonts', 'Alibaba PuHuiTi')
     },
     families: [
-      { name: 'Alibaba PuHuiTi', provider: 'alibaba-puhuiti', global: true }
+      { name: 'Alibaba PuHuiTi', global: true }
     ]
   },
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@movk/nuxt-docs",
   "type": "module",
-  "version": "1.17.4",
+  "version": "1.17.6",
   "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,9 +39,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@ai-sdk/gateway": "^3.0.91",
+    "@ai-sdk/gateway": "^3.0.93",
     "@ai-sdk/mcp": "^1.0.35",
-    "@ai-sdk/vue": "^3.0.149",
+    "@ai-sdk/vue": "^3.0.152",
     "@iconify-json/lucide": "^1.2.101",
     "@iconify-json/simple-icons": "^1.2.77",
     "@iconify-json/vscode-icons": "^1.2.45",
@@ -63,14 +63,14 @@
     "@takumi-rs/wasm": "^0.73.1",
     "@vueuse/core": "^14.2.1",
     "@vueuse/nuxt": "^14.2.1",
-    "ai": "^6.0.149",
+    "ai": "^6.0.152",
     "defu": "^6.1.7",
     "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.3.2",
+    "nuxt-og-image": "^6.3.3",
     "nuxt-site-config": "^4.0.7",
     "ohash": "^2.0.11",
     "pathe": "^2.0.3",

package/providers/alibaba-puhuiti.ts

@@ -13,12 +13,10 @@ const WEIGHT_MAP: Record<string, string> = {
   950: 'Black'
 }
 
-const FONT_FAMILY = 'Alibaba PuHuiTi'
-
-export function createAlibabaPuHuiTiProvider(cdnBase: string) {
+export function createAlibabaPuHuiTiProvider(cdnBase: string, name: string) {
   return defineFontProvider('alibaba-puhuiti', () => ({
     async resolveFont(fontFamily, options) {
-      if (fontFamily !== FONT_FAMILY) return undefined
+      if (fontFamily !== name) return undefined
 
       const weights = options.weights?.length
         ? options.weights.filter(w => WEIGHT_MAP[w])

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

@@ -2,18 +2,31 @@ import { z } from 'zod'
 
 export default defineMcpTool({
   description: '检索特定的示例实现代码和详细信息',
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
   inputSchema: {
     exampleName: z.string().describe('示例名称（PascalCase）')
   },
+  inputExamples: [
+    { exampleName: 'ButtonBasic' },
+    { exampleName: 'ModalOverlay' }
+  ],
   cache: '30m',
   async handler({ exampleName }) {
     try {
       const result = await $fetch<{ code: string }>(`/api/component-example/${exampleName}.json`)
-      return {
-        content: [{ type: 'text' as const, text: result.code }]
+      return result.code
+    } catch (error: unknown) {
+      const err = error as { statusCode?: number, response?: { status?: number } }
+      const status = err?.statusCode ?? err?.response?.status
+      if (status === 404) {
+        throw createError({ statusCode: 404, message: `示例 '${exampleName}' 未找到。使用 list_examples 工具查看所有可用示例。` })
       }
-    } catch {
-      throw createError({ statusCode: 404, message: `示例 '${exampleName}' 未找到。使用 list_examples 工具查看所有可用示例。` })
+      throw error
     }
   }
 })

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

@@ -2,88 +2,33 @@ import { z } from 'zod'
 
 export default defineMcpTool({
   description: `检索特定文档页面的完整内容和详细信息，使用 \`sections\` 参数仅获取特定的 h2 部分以减少响应大小。`,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
   inputSchema: {
     path: z.string().describe('从 list-pages 获取或用户提供的页面路径（例如 /docs/getting-started/installation）'),
     sections: z.array(z.string()).optional().describe('要返回的特定 h2 部分标题（例如 ["Usage","API"]）。如果省略，则返回完整文档。')
   },
+  inputExamples: [
+    { path: '/docs/components/button', sections: ['Usage', 'API'] },
+    { path: '/docs/getting-started/installation' }
+  ],
   cache: '30m',
   handler: async ({ path, sections }) => {
+    let content
     try {
-      const fullContent = await $fetch<string>(`/raw${path}.md`)
-
-      let content = fullContent
-
-      // If sections are specified, extract only those sections
-      if (sections && sections.length > 0) {
-        content = extractSections(fullContent, sections)
-      }
-
-      return {
-        content: [{ type: 'text', text: JSON.stringify(content, null, 2) }]
-      }
-    } catch (error) {
-      throw createError({ statusCode: 500, message: `获取页面失败: ${error}` })
-    }
-  }
-})
-
-/**
- * Extract specific sections from markdown content based on h2 headings
- */
-function extractSections(markdown: string, sectionTitles: string[]): string {
-  const lines = markdown.split('\n')
-  const result: string[] = []
-
-  // Normalize section titles for matching
-  const normalizedTitles = sectionTitles.map(t => t.toLowerCase().trim())
-
-  // Always include title (h1) and description (first blockquote)
-  let inHeader = true
-  for (const line of lines) {
-    if (inHeader) {
-      result.push(line)
-      // Stop after the description blockquote
-      if (line.startsWith('>') && result.length > 1) {
-        result.push('')
-        inHeader = false
-      }
-      continue
+      content = await $fetch<string>(`/raw${path}.md`)
+    } catch {
+      throw createError({ statusCode: 404, message: `获取页面失败: ${path}` })
     }
-    break
-  }
-
-  // Find and extract requested sections
-  let currentSection: string | null = null
-  let sectionContent: string[] = []
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]
-    if (!line) continue
-
-    // Check for h2 heading
-    if (line.startsWith('## ')) {
-      // Save previous section if it was requested
-      if (currentSection && normalizedTitles.includes(currentSection.toLowerCase())) {
-        result.push(...sectionContent)
-        result.push('')
-      }
-
-      // Start new section
-      currentSection = line.replace('## ', '').trim()
-      sectionContent = [line]
-      continue
+    // If sections are specified, extract only those sections
+    if (sections && sections.length > 0) {
+      content = extractSections(content, sections)
     }
 
-    // Add line to current section
-    if (currentSection) {
-      sectionContent.push(line)
-    }
-  }
-
-  // Don't forget the last section
-  if (currentSection && normalizedTitles.includes(currentSection.toLowerCase())) {
-    result.push(...sectionContent)
+    return content
   }
-
-  return result.join('\n').trim()
-}
+})

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

@@ -3,8 +3,14 @@ import { listComponentExamples } from '#component-example/nitro'
 
 export default defineMcpTool({
   description: '列出所有可用的示例和代码演示',
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
   cache: '1h',
   async handler() {
-    return await listComponentExamples()
+    return listComponentExamples()
   }
 })

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

@@ -3,6 +3,12 @@ import { inferSiteURL } from '../../../utils/meta'
 
 export default defineMcpTool({
   description: '列出所有入门指南和安装说明',
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
   cache: '30m',
   async handler() {
     const event = useEvent()
@@ -14,14 +20,12 @@ export default defineMcpTool({
       .select('id', 'title', 'description', 'path', 'navigation')
       .all()
 
-    const result = pages.map(page => ({
+    return pages.map(page => ({
       title: page.title,
       description: page.description,
       path: page.path,
       url: `${siteUrl}${page.path}`,
       navigation: page.navigation
     })).sort((a, b) => a.path.localeCompare(b.path))
-
-    return result
   }
 })

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

@@ -2,6 +2,12 @@ import { queryCollection } from '@nuxt/content/server'
 
 export default defineMcpTool({
   description: `列出所有可用的文档页面及其分类和基本信息。`,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
   cache: '1h',
   async handler() {
     const event = useEvent()

package/server/utils/extractSections.ts

@@ -0,0 +1,62 @@
+/**
+ * Extract specific h2 sections from markdown content.
+ * Always includes the title (h1) and description blockquote.
+ */
+export function extractSections(markdown: string, sectionTitles: string[]): string {
+  const lines = markdown.split('\n')
+  const result: string[] = []
+
+  // Normalize section titles for matching
+  const normalizedTitles = sectionTitles.map(t => t.toLowerCase().trim())
+
+  // Always include title (h1) and description (first blockquote)
+  let inHeader = true
+  for (const line of lines) {
+    if (inHeader) {
+      if (line.startsWith('## ')) {
+        inHeader = false
+        break
+      }
+      result.push(line)
+      // Stop after the description blockquote
+      if (line.startsWith('>') && result.length > 1) {
+        result.push('')
+        inHeader = false
+      }
+      continue
+    }
+    break
+  }
+
+  // Find and extract requested sections
+  let currentSection: string | null = null
+  let sectionContent: string[] = []
+
+  for (const line of lines) {
+    // Check for h2 heading
+    if (line.startsWith('## ')) {
+      // Save previous section if it was requested
+      if (currentSection && normalizedTitles.includes(currentSection.toLowerCase())) {
+        result.push(...sectionContent)
+        result.push('')
+      }
+
+      // Start new section
+      currentSection = line.replace('## ', '').trim()
+      sectionContent = [line]
+      continue
+    }
+
+    // Add line to current section
+    if (currentSection) {
+      sectionContent.push(line)
+    }
+  }
+
+  // Don't forget the last section
+  if (currentSection && normalizedTitles.includes(currentSection.toLowerCase())) {
+    result.push(...sectionContent)
+  }
+
+  return result.join('\n').trim()
+}

package/utils/component-meta.ts

@@ -52,7 +52,7 @@ export function createComponentMetaExcludeFilters(
     resolve('../app/components/content/ComponentProps.vue'),
     resolve('../app/components/content/ComponentSlots.vue'),
     resolve('../app/components/content/PageLastCommit.vue'),
-    resolve('./runtime/components/prose/Mermaid.vue')
+    resolve('./components/prose/Mermaid.vue')
   ]
 
   const userComponentPaths = [