@movk/nuxt-docs 1.8.1 → 1.9.0

package/README.md

@@ -20,6 +20,10 @@
 
 ### 🤖 AI 增强体验
 
+<div style="padding: 40px 0; display: flex; justify-content: center;">
+  <img src="https://docs.mhaibaraai.cn/ai/AiChat.png" alt="AiChat" width="400">
+</div>
+
 - **AI 聊天助手** - 内置智能文档助手，基于 Vercel AI SDK 支持多种 LLM 模型（Mistral、Qwen、OpenRouter）
 - **MCP Server 支持** - 集成 Model Context Protocol 服务器，为 AI 助手提供结构化的文档访问能力
 - **LLM 优化** - 通过 `nuxt-llms` 模块自动生成 `llms.txt` 和 `llms-full.txt`，为 AI 工具提供优化的文档索引

package/app/composables/useToolCall.ts

@@ -1,7 +1,9 @@
 export function useToolCall() {
   const tools: Record<string, string | ((args: any) => string)> = {
     'list-pages': '列出所有文档页面',
-    'get-page': (args: any) => `检索 ${args?.path || '页面'}`
+    'get-page': (args: any) => `检索 ${args?.path || '页面'}`,
+    'list-examples': '列出所有示例',
+    'get-example': (args: any) => `获取示例：${args?.exampleName || '示例'}`
   }
   return {
     tools

package/app/pages/docs/[...slug].vue

@@ -14,7 +14,7 @@ const { toc, github } = useAppConfig()
 const { data: page } = await useAsyncData(`docs-${kebabCase(route.path)}`, () => queryCollection('docs').path(route.path).first())
 
 if (!page.value) {
-  throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
+  throw createError({ status: 404, statusText: 'Page not found', fatal: true })
 }
 
 const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')

package/app/pages/index.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 const { data: page } = await useAsyncData('landing', () => queryCollection('landing').path('/').first())
 if (!page.value) {
-  throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
+  throw createError({ status: 404, statusText: 'Page not found', fatal: true })
 }
 
 const title = page.value.seo?.title || page.value.title

package/app/templates/releases.vue

@@ -3,7 +3,7 @@ import type { ButtonProps } from '@nuxt/ui'
 
 const { data: page } = await useAsyncData('releases', () => queryCollection('releases').first())
 if (!page.value) {
-  throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
+  throw createError({ status: 404, statusText: 'Page not found', fatal: true })
 }
 
 const title = page.value.seo?.title || page.value.title

package/content.config.ts

@@ -1,9 +1,8 @@
 import { existsSync } from 'node:fs'
 import { defineCollection, defineContentConfig } from '@nuxt/content'
 import { useNuxt } from '@nuxt/kit'
-import { asSeoCollection } from '@nuxtjs/seo/content'
 import { joinURL } from 'ufo'
-import { z } from 'zod/v4'
+import { z } from 'zod'
 
 const { options } = useNuxt()
 const cwd = joinURL(options.rootDir, 'content')
@@ -38,14 +37,14 @@ const PageHero = z.object({
 
 export default defineContentConfig({
   collections: {
-    landing: defineCollection(asSeoCollection({
+    landing: defineCollection({
       type: 'page',
       source: {
         cwd,
         include: 'index.md'
       }
-    })),
-    docs: defineCollection(asSeoCollection({
+    }),
+    docs: defineCollection({
       type: 'page',
       source: {
         cwd,
@@ -58,8 +57,8 @@ export default defineContentConfig({
           title: z.string().optional()
         })
       })
-    })),
-    releases: defineCollection(asSeoCollection({
+    }),
+    releases: defineCollection({
       type: 'page',
       source: {
         cwd,
@@ -71,6 +70,6 @@ export default defineContentConfig({
         releases: z.string(),
         hero: PageHero
       })
-    }))
+    })
   }
 })

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

@@ -1,5 +1,5 @@
 import { tool, stepCountIs, generateText } from 'ai'
-import { z } from 'zod/v4'
+import { z } from 'zod'
 
 function getSubAgentSystemPrompt(siteName: string) {
   return `您是 ${siteName} 的文档搜索代理。您的工作是从文档中查找并检索相关信息。

package/modules/config.ts

@@ -1,8 +1,8 @@
 import { createResolver, defineNuxtModule } from '@nuxt/kit'
-import { join } from 'pathe'
 import { defu } from 'defu'
 import { getGitBranch, getGitEnv, getLocalGitInfo } from '../utils/git'
 import { getPackageJsonMetadata, inferSiteURL } from '../utils/meta'
+import { createComponentMetaExcludeFilters } from '../utils/component-meta'
 
 export default defineNuxtModule({
   meta: {
@@ -17,28 +17,25 @@ export default defineNuxtModule({
     const url = inferSiteURL()
     const meta = await getPackageJsonMetadata(dir)
     const gitInfo = await getLocalGitInfo(dir) || getGitEnv()
-    const siteName = nuxt.options?.site?.name || meta.name || gitInfo?.name || ''
+    const siteName = meta.name || gitInfo?.name || ''
+
+    nuxt.options.site = defu(nuxt.options.site, {
+      url,
+      name: siteName,
+      debug: false
+    })
 
     nuxt.options.llms = defu(nuxt.options.llms, {
       domain: url || 'https://example.com',
       title: siteName,
       description: meta.description || '',
+      contentRawMarkdown: false as const,
       full: {
         title: siteName,
         description: meta.description || ''
       }
     })
 
-    nuxt.options.site = defu(nuxt.options.site, {
-      url,
-      name: siteName,
-      debug: false
-    })
-
-    nuxt.options.robots = defu(nuxt.options.robots, {
-      sitemap: url ? `${url.replace(/\/$/, '')}/sitemap.xml` : undefined
-    })
-
     nuxt.options.appConfig.header = defu(nuxt.options.appConfig.header, {
       title: siteName
     })
@@ -62,34 +59,16 @@ export default defineNuxtModule({
     })
 
     const layerPath = resolve('..')
-    const allowedComponents = [
-      resolve('../app/components/content/CommitChangelog.vue'),
-      resolve('../app/components/content/ComponentEmits.vue'),
-      resolve('../app/components/content/ComponentExample.vue'),
-      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')
-    ]
-    const userComponentPaths = [
-      join(dir, 'app/components'),
-      join(dir, 'components'),
-      join(dir, 'docs/app/components'),
-      join(dir, 'templates/*/app/components')
-    ]
 
     // @ts-ignore - component-meta is not typed
     nuxt.hook('component-meta:extend', (options: any) => {
+      const userInclude = (nuxt.options.componentMeta && typeof nuxt.options.componentMeta === 'object')
+        ? nuxt.options.componentMeta.include || []
+        : []
+
       options.exclude = [
         ...(options.exclude || []),
-        ({ filePath }: { filePath: string }) =>
-          filePath.startsWith(layerPath) && !allowedComponents.includes(filePath),
-        ({ filePath }: { filePath: string }) =>
-          userComponentPaths.some(path => filePath.startsWith(path))
+        ...createComponentMetaExcludeFilters(resolve, dir, layerPath, userInclude)
       ]
     })
   }

package/modules/css.ts

@@ -44,6 +44,8 @@ export default defineNuxtModule({
       }
     })
 
-    nuxt.options.css.unshift(cssTemplate.dst)
+    if (Array.isArray(nuxt.options.css)) {
+      nuxt.options.css.unshift(cssTemplate.dst)
+    }
   }
 })

package/nuxt.config.ts

@@ -12,10 +12,10 @@ export default defineNuxtConfig({
     '@nuxt/image',
     '@nuxt/a11y',
     '@nuxtjs/mcp-toolkit',
-    '@nuxtjs/seo',
     '@vueuse/nuxt',
     'nuxt-component-meta',
     'nuxt-llms',
+    'nuxt-og-image',
     'motion-v/nuxt',
     () => {
       extendViteConfig((config) => {
@@ -94,8 +94,8 @@ export default defineNuxtConfig({
     metaFields: {
       type: false,
       props: true,
-      slots: 'no-schema' as const,
-      events: 'no-schema' as const,
+      slots: 'no-schema',
+      events: 'no-schema',
       exposed: false
     },
     exclude: [
@@ -134,8 +134,5 @@ 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.8.1",
+  "version": "1.9.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,9 +28,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@ai-sdk/gateway": "^3.0.19",
-    "@ai-sdk/mcp": "^1.0.11",
-    "@ai-sdk/vue": "^3.0.45",
+    "@ai-sdk/gateway": "^3.0.22",
+    "@ai-sdk/mcp": "^1.0.13",
+    "@ai-sdk/vue": "^3.0.48",
     "@iconify-json/lucide": "^1.2.86",
     "@iconify-json/ph": "^1.2.2",
     "@iconify-json/simple-icons": "^1.2.67",
@@ -40,26 +40,26 @@
     "@nuxt/a11y": "^1.0.0-alpha.1",
     "@nuxt/content": "^3.11.0",
     "@nuxt/image": "^2.0.0",
-    "@nuxt/kit": "^4.2.2",
+    "@nuxt/kit": "^4.3.0",
     "@nuxt/ui": "^4.4.0",
     "@nuxtjs/mcp-toolkit": "^0.6.2",
-    "@nuxtjs/seo": "^3.3.0",
     "@octokit/rest": "^22.0.1",
     "@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.45",
+    "ai": "^6.0.48",
     "defu": "^6.1.4",
     "dompurify": "^3.3.1",
     "exsolve": "^1.0.8",
     "git-url-parse": "^16.1.0",
     "mermaid": "^11.12.2",
     "motion-v": "^1.9.0",
-    "nuxt": "^4.2.2",
+    "nuxt": "^4.3.0",
     "nuxt-component-meta": "^0.17.1",
     "nuxt-llms": "^0.2.0",
+    "nuxt-og-image": "^5.1.13",
     "ohash": "^2.0.11",
     "pathe": "^2.0.3",
     "pkg-types": "^2.3.0",
@@ -70,6 +70,6 @@
     "shiki-transformer-color-highlight": "^1.0.0",
     "tailwindcss": "^4.1.18",
     "ufo": "^1.6.3",
-    "zod": "^4.3.5"
+    "zod": "^4.3.6"
   }
 }

package/server/api/component-example.get.ts

@@ -10,8 +10,8 @@ export default defineEventHandler((event) => {
     const component = components[pascalCase(componentName)]
     if (!component) {
       throw createError({
-        statusMessage: 'Example not found!',
-        statusCode: 404
+        statusText: 'Example not found!',
+        status: 404
       })
     }
     return component

package/server/api/github/commits.get.ts

@@ -10,8 +10,8 @@ export default defineCachedEventHandler(async (event) => {
 
   if (!paths.length || !paths[0]) {
     throw createError({
-      statusCode: 400,
-      statusMessage: 'Path is required'
+      status: 400,
+      statusText: 'Path is required'
     })
   }
 
@@ -19,8 +19,8 @@ export default defineCachedEventHandler(async (event) => {
 
   if (!github || typeof github === 'boolean') {
     throw createError({
-      statusCode: 500,
-      statusMessage: 'GitHub configuration is not available'
+      status: 500,
+      statusText: 'GitHub configuration is not available'
     })
   }
 

package/server/api/github/last-commit.get.ts

@@ -8,8 +8,8 @@ export default defineCachedEventHandler(async (event) => {
   const { path } = getQuery(event) as { path: string }
   if (!path) {
     throw createError({
-      statusCode: 400,
-      statusMessage: 'Path is required'
+      status: 400,
+      statusText: 'Path is required'
     })
   }
 
@@ -17,8 +17,8 @@ export default defineCachedEventHandler(async (event) => {
 
   if (!github || typeof github === 'boolean') {
     throw createError({
-      statusCode: 500,
-      statusMessage: 'GitHub configuration is not available'
+      status: 500,
+      statusText: 'GitHub configuration is not available'
     })
   }
 

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

@@ -0,0 +1,19 @@
+import { z } from 'zod'
+
+export default defineMcpTool({
+  description: '检索特定的 UI 示例实现代码和详细信息',
+  inputSchema: {
+    exampleName: z.string().describe('示例名称（PascalCase）')
+  },
+  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 }]
+      }
+    } catch {
+      return errorResult(`示例 '${exampleName}' 未找到。使用 list_examples 工具查看所有可用示例。`)
+    }
+  }
+})

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

@@ -1,9 +1,9 @@
-import { z } from 'zod/v4'
+import { z } from 'zod'
 import { queryCollection } from '@nuxt/content/server'
 import { inferSiteURL } from '../../../utils/meta'
 
 export default defineMcpTool({
-  description: `检索特定文档页面的完整内容和详细信息。
+  description: `检索特定文档页面的完整内容和详细信息，使用 \`sections\` 参数仅获取特定的 h2 部分以减少响应大小。'
 
 何时使用：当你知道文档页面的确切路径时使用。常见用例：
 - 用户请求特定页面：「显示入门指南」→ /docs/getting-started
@@ -15,10 +15,11 @@ export default defineMcpTool({
 
 工作流程：此工具返回完整的页面内容，包括标题、描述和完整的 markdown。当你需要从特定文档页面提供详细答案或代码示例时使用。`,
   inputSchema: {
-    path: z.string().describe('从 list-pages 获取或用户提供的页面路径（例如 /docs/getting-started/installation）')
+    path: z.string().describe('从 list-pages 获取或用户提供的页面路径（例如 /docs/getting-started/installation）'),
+    sections: z.array(z.string()).optional().describe('要返回的特定 h2 部分标题（例如 ["Usage","API"]）。如果省略，则返回完整文档。')
   },
-  cache: '1h',
-  handler: async ({ path }) => {
+  cache: '30m',
+  handler: async ({ path, sections }) => {
     const event = useEvent()
     const siteUrl = import.meta.dev ? 'http://localhost:3000' : inferSiteURL()
 
@@ -35,10 +36,17 @@ export default defineMcpTool({
         }
       }
 
-      const content = await $fetch<string>(`/raw${path}.md`, {
+      const fullContent = await $fetch<string>(`/raw${path}.md`, {
         baseURL: siteUrl
       })
 
+      let content = fullContent
+
+      // If sections are specified, extract only those sections
+      if (sections && sections.length > 0) {
+        content = extractSections(fullContent, sections)
+      }
+
       const result = {
         title: page.title,
         path: page.path,
@@ -58,3 +66,64 @@ export default defineMcpTool({
     }
   }
 })
+
+/**
+ * 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
+    }
+    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
+    }
+
+    // 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/server/mcp/tools/list-examples.ts

@@ -0,0 +1,14 @@
+// @ts-expect-error - no types available
+import components from '#component-example/nitro'
+
+export default defineMcpTool({
+  description: '列出所有可用的 UI 示例和代码演示',
+  cache: '1h',
+  handler() {
+    const examples = Object.entries<{ pascalName: string }>(components).map(([_key, value]) => {
+      return value.pascalName
+    })
+
+    return jsonResult(examples)
+  }
+})

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

@@ -19,7 +19,7 @@ export default defineMcpTool({
 - path：用于 get-page 的确切路径
 - description：页面内容的简要摘要
 - url：完整 URL 供参考`,
-  cache: '1h',
+  cache: '30m',
   handler: async () => {
     const event = useEvent()
     const siteUrl = import.meta.dev ? 'http://localhost:3000' : getRequestURL(event).origin

package/server/plugins/llms.ts

@@ -1,24 +1,19 @@
+import type { H3Event } from 'h3'
+import type { PageCollectionItemBase } from '@nuxt/content'
+
 export default defineNitroPlugin((nitroApp) => {
-  /**
-   * @see
-   * https://github.com/nuxt-content/nuxt-llms?tab=readme-ov-file#readme
-   */
-  nitroApp.hooks.hook('llms:generate', (_, { sections, domain }) => {
-    // Transform links except for "Documentation Sets"
-    sections.forEach((section) => {
-      if (section.title !== 'Documentation Sets') {
-        section.links = section.links?.map(link => ({
-          ...link,
-          href: `${link.href.replace(new RegExp(`^${domain}`), `${domain}/raw`)}.md`
-        }))
-      }
-    })
+  nitroApp.hooks.hook('content:llms:generate:document', async (event: H3Event, doc: PageCollectionItemBase) => {
+    await transformMDC(event, doc as any)
+  })
 
+  nitroApp.hooks.hook('llms:generate', (_, { sections }) => {
     // Move "Documentation Sets" to the end
     const docSetIdx = sections.findIndex(s => s.title === 'Documentation Sets')
     if (docSetIdx !== -1) {
       const [docSet] = sections.splice(docSetIdx, 1)
-      sections.push(docSet)
+      if (docSet) {
+        sections.push(docSet)
+      }
     }
   })
 })

package/server/routes/raw/[...slug].md.get.ts

@@ -1,21 +1,41 @@
-import type { Collections } from '@nuxt/content'
-import { queryCollection } from '@nuxt/content/server'
-import { stringify } from 'minimark/stringify'
 import { withLeadingSlash } from 'ufo'
+import { stringify } from 'minimark/stringify'
+import { queryCollection } from '@nuxt/content/server'
+import type { Collections, PageCollectionItemBase } from '@nuxt/content'
+import { getRouterParams, eventHandler, createError, setHeader } from 'h3'
+import collections from '#content/manifest'
+import { transformMDC } from '../../utils/transformMDC'
 
-export default defineEventHandler(async (event) => {
+export default eventHandler(async (event) => {
   const slug = getRouterParams(event)['slug.md']
   if (!slug?.endsWith('.md')) {
-    throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
+    throw createError({ status: 404, statusText: 'Page not found', fatal: true })
   }
 
-  const path = withLeadingSlash(slug.replace('.md', ''))
+  let path = withLeadingSlash(slug.replace('.md', ''))
+  if (path.endsWith('/index')) {
+    path = path.substring(0, path.length - 6)
+  }
+
+  const _collections = Object.entries(collections as unknown as Record<string, { type: string }>)
+    .filter(([_key, value]) => value.type === 'page')
+    .map(([key]) => key) as string[]
+
+  let page: PageCollectionItemBase | null = null
+  for (const collection of _collections) {
+    page = await queryCollection(event, collection as keyof Collections).path(path).first() as PageCollectionItemBase | null
+    if (page) {
+      break
+    }
+  }
 
-  const page = await queryCollection(event, 'docs' as keyof Collections).path(path).first()
   if (!page) {
-    throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
+    throw createError({ status: 404, statusText: 'Page not found', fatal: true })
   }
 
+  // Transform MDC components to standard elements for LLM consumption
+  await transformMDC(event, page as any)
+
   // Add title and description to the top of the page if missing
   if (page.body.value[0]?.[0] !== 'h1') {
     page.body.value.unshift(['blockquote', {}, page.description])

package/server/utils/transformMDC.ts

@@ -0,0 +1,559 @@
+import type { H3Event } from 'h3'
+import { camelCase, kebabCase, upperFirst } from 'scule'
+import { visit } from '@nuxt/content/runtime'
+// @ts-expect-error - no types available
+import components from '#component-example/nitro'
+
+type Document = {
+  title: string
+  body: any
+}
+
+function replaceNodeWithPre(node: any[], language: string, code: string, filename?: string) {
+  node[0] = 'pre'
+  node[1] = { language, code }
+  if (filename) node[1].filename = filename
+}
+
+function visitAndReplace(doc: Document, type: string, handler: (node: any[]) => void) {
+  visit(doc.body, (node) => {
+    if (Array.isArray(node) && node[0] === type) {
+      handler(node)
+    }
+    return true
+  }, node => node)
+}
+
+export async function transformMDC(event: H3Event, doc: Document): Promise<Document> {
+  // Transform commit-changelog to changelog content
+  const changelogNodes: any[][] = []
+  visitAndReplace(doc, 'commit-changelog', (node) => {
+    changelogNodes.push(node)
+  })
+
+  if (changelogNodes.length) {
+    const { github } = useAppConfig() as { github: Record<string, any> }
+
+    await Promise.all(changelogNodes.map(async (node) => {
+      const attrs = node[1] || {}
+      const basePath = attrs['commit-path'] || github?.commitPath || 'src'
+      const filePrefix = attrs.prefix ? `${attrs.prefix}/` : ''
+      const fileExtension = attrs.suffix || github?.suffix || 'vue'
+      const fileName = attrs.name || doc.title || ''
+      const casing = attrs.casing || github?.casing || 'auto'
+
+      const transformedName = (() => {
+        switch (casing) {
+          case 'kebab': return kebabCase(fileName)
+          case 'camel': return camelCase(fileName)
+          case 'pascal': return upperFirst(camelCase(fileName))
+          case 'auto':
+          default:
+            return fileExtension === 'vue'
+              ? upperFirst(camelCase(fileName))
+              : camelCase(fileName)
+        }
+      })()
+
+      const filePath = `${basePath}/${filePrefix}${transformedName}.${fileExtension}`
+      const githubUrl = github?.url || ''
+
+      try {
+        const commits = await $fetch<Array<{ sha: string, message: string }>>('/api/github/commits', {
+          query: { path: filePath, author: attrs.author }
+        })
+
+        if (!commits?.length) {
+          node[0] = 'p'
+          node[1] = {}
+          node[2] = 'No recent changes.'
+          node.length = 3
+          return
+        }
+
+        const lines = commits.map((commit) => {
+          const shortSha = commit.sha.slice(0, 5)
+          const message = commit.message.replace(/\(.*?\)/, '').replace(/#(\d+)/g, `[#$1](${githubUrl}/issues/$1)`)
+          return `- [\`${shortSha}\`](${githubUrl}/commit/${commit.sha}) — ${message}`
+        })
+
+        node[0] = 'p'
+        node[1] = {}
+        node[2] = lines.join('\n')
+        node.length = 3
+      } catch {
+        node[0] = 'p'
+        node[1] = {}
+        node[2] = githubUrl
+          ? `See the [releases page](${githubUrl}/releases) for the latest changes.`
+          : 'No recent changes.'
+        node.length = 3
+      }
+    }))
+  }
+
+  // Transform component-props, component-slots, component-emits to markdown tables
+  const DEFAULT_IGNORE_PROPS = [
+    'activeClass', 'inactiveClass', 'exactActiveClass', 'ariaCurrentValue',
+    'href', 'rel', 'noRel', 'prefetch', 'prefetchOn', 'noPrefetch',
+    'prefetchedClass', 'replace', 'exact', 'exactQuery', 'exactHash',
+    'external', 'onClick', 'viewTransition', 'enterKeyHint',
+    'form', 'formaction', 'formenctype', 'formmethod', 'formnovalidate', 'formtarget'
+  ]
+
+  const metaNodes: { node: any[], type: 'props' | 'slots' | 'emits' }[] = []
+  for (const type of ['component-props', 'component-slots', 'component-emits'] as const) {
+    visitAndReplace(doc, type, (node) => {
+      metaNodes.push({ node, type: type.replace('component-', '') as 'props' | 'slots' | 'emits' })
+    })
+  }
+
+  if (metaNodes.length) {
+    await Promise.all(metaNodes.map(async ({ node, type }) => {
+      const attrs = node[1] || {}
+      const slug = attrs.slug || doc.title || ''
+      const camelName = camelCase(slug)
+      const componentName = type === 'props' && attrs.prose
+        ? `Prose${upperFirst(camelName)}`
+        : upperFirst(camelName)
+
+      try {
+        const meta = await $fetch<{ meta: { props?: any[], slots?: any[], events?: any[] } }>(`/api/component-meta/${componentName}.json`)
+
+        let markdown = ''
+
+        if (type === 'props') {
+          const ignoreList = attrs.ignore ? String(attrs.ignore).split(',').map((s: string) => s.trim()) : DEFAULT_IGNORE_PROPS
+          const props = (meta?.meta?.props || [])
+            .filter((p: any) => !ignoreList.includes(p.name))
+            .sort((a: any, b: any) => {
+              if (a.name === 'as') return -1
+              if (b.name === 'as') return 1
+              if (a.name === 'ui') return 1
+              if (b.name === 'ui') return -1
+              return 0
+            })
+
+          if (props.length) {
+            markdown = '| Prop | Default | Type |\n| --- | --- | --- |\n'
+            markdown += props.map((p: any) => {
+              const def = p.default?.replace(' as never', '').replace(/^"(.*)"$/, '\'$1\'') || ''
+              const desc = p.description ? ` - ${p.description}` : ''
+              return `| \`${p.name}\` | \`${def || '-'}\` | \`${p.type || '-'}\`${desc} |`
+            }).join('\n')
+          } else {
+            markdown = 'No props available.'
+          }
+        } else if (type === 'slots') {
+          const slots = meta?.meta?.slots || []
+          if (slots.length) {
+            markdown = '| Slot | Type |\n| --- | --- |\n'
+            markdown += slots.map((s: any) => {
+              const desc = s.description ? ` - ${s.description}` : ''
+              return `| \`${s.name}\` | \`${s.type || '-'}\`${desc} |`
+            }).join('\n')
+          } else {
+            markdown = 'No slots available.'
+          }
+        } else {
+          const events = meta?.meta?.events || []
+          if (events.length) {
+            markdown = '| Event | Type |\n| --- | --- |\n'
+            markdown += events.map((e: any) => `| \`${e.name}\` | \`${e.type || '-'}\` |`).join('\n')
+          } else {
+            markdown = 'No events available.'
+          }
+        }
+
+        node[0] = 'p'
+        node[1] = {}
+        node[2] = markdown
+        node.length = 3
+      } catch {
+        node[0] = 'p'
+        node[1] = {}
+        node[2] = `Component metadata not available for \`${componentName}\`.`
+        node.length = 3
+      }
+    }))
+  }
+
+  // Transform component-example to code block
+  visitAndReplace(doc, 'component-example', (node) => {
+    const camelName = camelCase(node[1]['name'])
+    const name = camelName.charAt(0).toUpperCase() + camelName.slice(1)
+    const code = components[name].code
+    replaceNodeWithPre(node, 'vue', code, `${name}.vue`)
+  })
+
+  // Transform callout components (tip, note, warning, caution, callout) to blockquotes
+  const calloutTypes = ['tip', 'note', 'warning', 'caution', 'callout']
+  const calloutLabels: Record<string, string> = {
+    tip: 'TIP',
+    note: 'NOTE',
+    warning: 'WARNING',
+    caution: 'CAUTION',
+    callout: 'NOTE'
+  }
+
+  for (const calloutType of calloutTypes) {
+    visitAndReplace(doc, calloutType, (node) => {
+      const attrs = node[1] || {}
+      const content = node.slice(2)
+      const label = calloutLabels[calloutType]
+
+      // Build the blockquote content
+      let blockquoteText = `> [!${label}]`
+
+      // Add link if present
+      if (attrs.to) {
+        blockquoteText += `\n> See: ${attrs.to}`
+      }
+
+      // Extract text content from children
+      const extractText = (children: any[]): string => {
+        return children.map((child) => {
+          if (typeof child === 'string') return child
+          if (Array.isArray(child)) {
+            const tag = child[0]
+            const childAttrs = child[1] || {}
+            const childContent = child.slice(2)
+            if (tag === 'code') return `\`${extractText(childContent)}\``
+            if (tag === 'a') return `[${extractText(childContent)}](${childAttrs.href || ''})`
+            if (tag === 'pre') {
+              const lang = childAttrs.language || ''
+              const code = childAttrs.code || extractText(childContent)
+              return `\n\`\`\`${lang}\n${code}\n\`\`\`\n`
+            }
+            return extractText(childContent)
+          }
+          return ''
+        }).join('')
+      }
+
+      if (content.length > 0) {
+        const textContent = extractText(content)
+        if (textContent.trim()) {
+          blockquoteText += `\n> ${textContent.trim().split('\n').join('\n> ')}`
+        }
+      }
+
+      node[0] = 'p'
+      node[1] = {}
+      node[2] = blockquoteText
+      node.length = 3
+    })
+  }
+
+  // Transform framework-only - extract content from both slots and label them
+  visitAndReplace(doc, 'framework-only', (node) => {
+    const children = node.slice(2)
+    let nuxtContent = ''
+    let vueContent = ''
+
+    // Helper to extract text from AST nodes
+    const extractContent = (nodes: any[]): string => {
+      return nodes.map((n: any) => {
+        if (typeof n === 'string') return n
+        if (Array.isArray(n)) {
+          const tag = n[0]
+          const attrs = n[1] || {}
+          const content = n.slice(2)
+          if (tag === 'pre') {
+            const lang = attrs.language || ''
+            const code = attrs.code || ''
+            return `\n\`\`\`${lang}\n${code}\n\`\`\`\n`
+          }
+          return extractContent(content)
+        }
+        return ''
+      }).join('')
+    }
+
+    for (const child of children) {
+      if (Array.isArray(child) && child[0] === 'template') {
+        const slotAttr = child[1]?.['v-slot:nuxt'] !== undefined
+          ? 'nuxt'
+          : child[1]?.['v-slot:vue'] !== undefined ? 'vue' : null
+        if (slotAttr === 'nuxt') {
+          nuxtContent = extractContent(child.slice(2))
+        } else if (slotAttr === 'vue') {
+          vueContent = extractContent(child.slice(2))
+        }
+      }
+    }
+
+    let output = ''
+    if (nuxtContent.trim()) {
+      output += '**Nuxt:**\n' + nuxtContent.trim()
+    }
+    if (vueContent.trim()) {
+      if (output) output += '\n\n'
+      output += '**Vue:**\n' + vueContent.trim()
+    }
+
+    node[0] = 'p'
+    node[1] = {}
+    node[2] = output || ''
+    node.length = 3
+  })
+
+  // Transform badge to inline text
+  visitAndReplace(doc, 'badge', (node) => {
+    const attrs = node[1] || {}
+    const label = attrs.label || ''
+    node[0] = 'code'
+    node[1] = {}
+    node[2] = label
+    node.length = 3
+  })
+
+  // Transform card components to markdown sections
+  visitAndReplace(doc, 'card', (node) => {
+    const attrs = node[1] || {}
+    const content = node.slice(2)
+    const title = attrs.title || ''
+
+    // Extract text content from children
+    const extractText = (children: any[]): string => {
+      return children.map((child) => {
+        if (typeof child === 'string') return child
+        if (Array.isArray(child)) {
+          const tag = child[0]
+          const childContent = child.slice(2)
+          if (tag === 'code') return `\`${extractText(childContent)}\``
+          if (tag === 'a') return `[${extractText(childContent)}](${child[1]?.href || ''})`
+          return extractText(childContent)
+        }
+        return ''
+      }).join('')
+    }
+
+    let cardText = title ? `**${title}**` : ''
+    if (content.length > 0) {
+      const textContent = extractText(content)
+      if (textContent.trim()) {
+        cardText += cardText ? `\n${textContent.trim()}` : textContent.trim()
+      }
+    }
+
+    node[0] = 'p'
+    node[1] = {}
+    node[2] = cardText
+    node.length = 3
+  })
+
+  // Transform accordion-item to Q&A format
+  visitAndReplace(doc, 'accordion-item', (node) => {
+    const attrs = node[1] || {}
+    const content = node.slice(2)
+    const label = attrs.label || ''
+
+    // Extract text content from children
+    const extractText = (children: any[]): string => {
+      return children.map((child) => {
+        if (typeof child === 'string') return child
+        if (Array.isArray(child)) {
+          const tag = child[0]
+          const childContent = child.slice(2)
+          if (tag === 'code') return `\`${extractText(childContent)}\``
+          if (tag === 'a') return `[${extractText(childContent)}](${child[1]?.href || ''})`
+          if (tag === 'p') return extractText(childContent)
+          return extractText(childContent)
+        }
+        return ''
+      }).join('')
+    }
+
+    let itemText = label ? `**Q: ${label}**` : ''
+    if (content.length > 0) {
+      const textContent = extractText(content)
+      if (textContent.trim()) {
+        itemText += `\n\nA: ${textContent.trim()}`
+      }
+    }
+
+    node[0] = 'p'
+    node[1] = {}
+    node[2] = itemText
+    node.length = 3
+  })
+
+  // Remove wrapper elements by extracting children content
+  const wrapperTypes = ['card-group', 'accordion', 'steps', 'code-group', 'code-collapse', 'tabs']
+  for (const wrapperType of wrapperTypes) {
+    visitAndReplace(doc, wrapperType, (node) => {
+      const children = node.slice(2)
+
+      // Extract text from transformed children (they should be paragraphs now)
+      const extractFromChildren = (nodes: any[]): string => {
+        return nodes.map((child: any) => {
+          if (typeof child === 'string') return child
+          if (Array.isArray(child)) {
+            const tag = child[0]
+            const attrs = child[1] || {}
+            const content = child.slice(2)
+            // Handle pre/code blocks
+            if (tag === 'pre') {
+              const lang = attrs.language || ''
+              const code = attrs.code || ''
+              return `\n\`\`\`${lang}\n${code}\n\`\`\`\n`
+            }
+            // Handle paragraphs and other text
+            if (tag === 'p') {
+              const text = content.map((c: any) => typeof c === 'string' ? c : '').join('')
+              return text + '\n\n'
+            }
+            return extractFromChildren(content)
+          }
+          return ''
+        }).join('')
+      }
+
+      const extracted = extractFromChildren(children).trim()
+      node[0] = 'p'
+      node[1] = {}
+      node[2] = extracted
+      node.length = 3
+    })
+  }
+
+  // Transform field-group to remove wrapper (fields already handled)
+  const fieldWrappers = ['field-group', 'collapsible']
+  for (const wrapperType of fieldWrappers) {
+    visitAndReplace(doc, wrapperType, (node) => {
+      const children = node.slice(2)
+      const extractFromChildren = (nodes: any[]): string => {
+        return nodes.map((child: any) => {
+          if (typeof child === 'string') return child
+          if (Array.isArray(child)) {
+            const tag = child[0]
+            const attrs = child[1] || {}
+            const content = child.slice(2)
+            if (tag === 'pre') {
+              const lang = attrs.language || ''
+              const code = attrs.code || ''
+              return `\n\`\`\`${lang}\n${code}\n\`\`\`\n`
+            }
+            if (tag === 'p') {
+              const text = content.map((c: any) => typeof c === 'string' ? c : '').join('')
+              return text + '\n\n'
+            }
+            return extractFromChildren(content)
+          }
+          return ''
+        }).join('')
+      }
+      const extracted = extractFromChildren(children).trim()
+      node[0] = 'p'
+      node[1] = {}
+      node[2] = extracted
+      node.length = 3
+    })
+  }
+
+  // Transform field to a definition format
+  visitAndReplace(doc, 'field', (node) => {
+    const attrs = node[1] || {}
+    const content = node.slice(2)
+    const name = attrs.name || ''
+    const type = attrs.type || ''
+    const required = attrs.required === 'true' || attrs[':required'] === 'true'
+
+    const extractText = (nodes: any[]): string => {
+      return nodes.map((child: any) => {
+        if (typeof child === 'string') return child
+        if (Array.isArray(child)) {
+          const content = child.slice(2)
+          return extractText(content)
+        }
+        return ''
+      }).join('')
+    }
+
+    let fieldText = `**${name}**`
+    if (type) fieldText += ` (\`${type}\`)`
+    if (required) fieldText += ' *required*'
+    const desc = extractText(content).trim()
+    if (desc) fieldText += `: ${desc}`
+
+    node[0] = 'p'
+    node[1] = {}
+    node[2] = fieldText
+    node.length = 3
+  })
+
+  // Transform code-preview to extract the Vue code as a code block
+  visitAndReplace(doc, 'code-preview', (node) => {
+    const children = node.slice(2)
+
+    const extractVueCode = (nodes: any[]): string => {
+      return nodes.map((child: any) => {
+        if (typeof child === 'string') return child
+        if (Array.isArray(child)) {
+          const tag = child[0]
+          const attrs = child[1] || {}
+          const content = child.slice(2)
+          // Build the opening tag
+          let tagStr = `<${tag}`
+          for (const [key, val] of Object.entries(attrs)) {
+            if (key.startsWith(':') || key.startsWith('v-')) {
+              tagStr += ` ${key}=${val}`
+            } else if (typeof val === 'string') {
+              tagStr += ` ${key}=${val}`
+            }
+          }
+          const innerContent = extractVueCode(content)
+          if (innerContent.trim()) {
+            tagStr += `>\n${innerContent}</${tag}>`
+          } else {
+            tagStr += ' />'
+          }
+          return tagStr
+        }
+        return ''
+      }).join('\n')
+    }
+
+    const vueCode = extractVueCode(children).trim()
+    node[0] = 'pre'
+    node[1] = { language: 'vue', code: `<template>\n  ${vueCode.split('\n').join('\n  ')}\n</template>` }
+    node.length = 2
+  })
+
+  // Transform icons-theme and icons-theme-select to placeholder
+  visitAndReplace(doc, 'icons-theme', (node) => {
+    node[0] = 'p'
+    node[1] = {}
+    node[2] = '*See the interactive theme picker on the documentation website.*'
+    node.length = 3
+  })
+
+  visitAndReplace(doc, 'icons-theme-select', (node) => {
+    node[0] = 'p'
+    node[1] = {}
+    node[2] = ''
+    node.length = 3
+  })
+
+  // Transform supported-languages to placeholder
+  visitAndReplace(doc, 'supported-languages', (node) => {
+    node[0] = 'p'
+    node[1] = {}
+    node[2] = '*See the full list of supported languages on the documentation website.*'
+    node.length = 3
+  })
+
+  // Transform u-button to markdown link
+  visitAndReplace(doc, 'u-button', (node) => {
+    const attrs = node[1] || {}
+    const label = attrs.label || ''
+    const to = attrs.to || ''
+    node[0] = 'p'
+    node[1] = {}
+    node[2] = to ? `[${label}](${to})` : label
+    node.length = 3
+  })
+
+  return doc
+}

package/utils/component-meta.ts

@@ -0,0 +1,97 @@
+import type { Resolver } from '@nuxt/kit'
+import { join } from 'pathe'
+
+/**
+ * 匹配组件是否符合用户定义的 include 模式
+ * @param filePath 组件文件路径
+ * @param pascalName 组件 PascalCase 名称
+ * @param includePatterns 包含模式数组(字符串 glob、正则表达式或函数)
+ * @returns 是否匹配
+ */
+function matchesUserInclude(
+  filePath: string,
+  pascalName: string,
+  includePatterns: Array<string | RegExp | ((component: { filePath: string, pascalName: string }) => boolean)>
+): boolean {
+  return includePatterns.some((pattern) => {
+    if (typeof pattern === 'string') {
+      // 简单的 glob 支持: ** 匹配任意路径，* 匹配非路径分隔符
+      const regexPattern = pattern
+        .replace(/\*\*/g, '{{DOUBLE_STAR}}')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\{\{DOUBLE_STAR\}\}/g, '.*')
+      const regex = new RegExp(regexPattern)
+      return regex.test(filePath) || filePath.includes(pattern)
+    }
+    if (pattern instanceof RegExp) {
+      return pattern.test(filePath) || pattern.test(pascalName)
+    }
+    if (typeof pattern === 'function') {
+      return pattern({ filePath, pascalName })
+    }
+    return false
+  })
+}
+
+/**
+ * 检查组件是否为用户组件
+ * @param filePath 组件文件路径
+ * @param userComponentPaths 用户组件路径数组
+ * @returns 是否为用户组件
+ */
+export function isUserComponent(filePath: string, userComponentPaths: string[]): boolean {
+  return userComponentPaths.some(path => filePath.startsWith(path))
+}
+
+/**
+ * 创建 component-meta exclude 过滤器
+ * @param layerPath layer 路径
+ * @param allowedComponents 允许的组件列表
+ * @param userComponentPaths 用户组件路径数组
+ * @param userInclude 用户定义的 include 模式
+ * @returns exclude 过滤器数组
+ */
+export function createComponentMetaExcludeFilters(
+  resolve: Resolver['resolve'],
+  dir: string,
+  layerPath: string,
+  userInclude: Array<string | RegExp | ((component: { filePath: string, pascalName: string }) => boolean)>
+) {
+  const allowedComponents = [
+    resolve('../app/components/content/CommitChangelog.vue'),
+    resolve('../app/components/content/ComponentEmits.vue'),
+    resolve('../app/components/content/ComponentExample.vue'),
+    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')
+  ]
+
+  const userComponentPaths = [
+    join(dir, 'app/components'),
+    join(dir, 'components'),
+    join(dir, 'docs/app/components'),
+    join(dir, 'templates/*/app/components')
+  ]
+
+  return [
+    // 排除 layer 中不在白名单的组件
+    ({ filePath }: { filePath: string }) =>
+      filePath.startsWith(layerPath) && !allowedComponents.includes(filePath),
+    // 排除用户组件中不符合 include 规则的组件
+    ({ filePath, pascalName }: { filePath: string, pascalName: string }) => {
+      const isUser = isUserComponent(filePath, userComponentPaths)
+      if (!isUser) return false
+
+      // 如果没有指定 include，排除所有用户组件
+      if (userInclude.length === 0) return true
+
+      // 如果指定了 include，排除不匹配的组件
+      return !matchesUserInclude(filePath, pascalName, userInclude)
+    }
+  ]
+}