@movk/nuxt-docs 1.13.1 → 1.14.0

package/app/utils/shiki-transformer-icon-highlight.ts

@@ -0,0 +1,89 @@
+import type { ShikiTransformer } from '@shikijs/core'
+
+export interface TransformerIconHighlightOptions {
+  /**
+   * Custom function to render the icon HTML
+   * @default Uses Iconify API with mask mode
+   */
+  htmlIcon?: (icon: string) => string
+}
+
+// Common icon collections to validate against (sorted by length descending for proper matching)
+const ICON_COLLECTIONS = [
+  'simple-icons',
+  'vscode-icons',
+  'tabler',
+  'lucide',
+  'logos',
+  'ph'
+]
+
+function parseIconName(text: string): { collection: string, name: string, format: 'i' | 'colon' } | null {
+  // Strip quotes if present (single, double, or backticks)
+  let cleanText = text
+  if (/^['"`].*['"`]$/.test(text)) {
+    cleanText = text.slice(1, -1)
+  }
+
+  // Try i-{collection}-{name} format
+  if (cleanText.startsWith('i-')) {
+    const rest = cleanText.slice(2)
+    for (const collection of ICON_COLLECTIONS) {
+      if (rest.startsWith(`${collection}-`)) {
+        const name = rest.slice(collection.length + 1)
+        if (name && /^[a-z0-9]+(?:-[a-z0-9]+)*$/i.test(name)) {
+          return { collection, name, format: 'i' }
+        }
+      }
+    }
+  }
+
+  // Try {collection}:{name} format
+  const colonIndex = cleanText.indexOf(':')
+  if (colonIndex > 0) {
+    const collection = cleanText.slice(0, colonIndex)
+    const name = cleanText.slice(colonIndex + 1)
+    if (ICON_COLLECTIONS.includes(collection) && name && /^[a-z0-9]+(?:-[a-z0-9]+)*$/i.test(name)) {
+      return { collection, name, format: 'colon' }
+    }
+  }
+
+  return null
+}
+
+export function transformerIconHighlight(options: TransformerIconHighlightOptions = {}): ShikiTransformer {
+  const { htmlIcon } = options
+
+  return {
+    name: 'shiki-transformer-icon-highlight',
+    span(hast, _line, _col, _lineElement, token) {
+      const text = token.content
+
+      // Try to parse as an icon
+      const parsed = parseIconName(text)
+      if (!parsed) return
+
+      const iconIdentifier = `${parsed.collection}:${parsed.name}`
+      // Add color=black for mask-image to work properly (mask uses luminance)
+      const iconUrl = `https://api.iconify.design/${iconIdentifier}.svg?color=%23000`
+
+      // Create the icon element as a proper HAST element
+      const iconElement = htmlIcon
+        ? { type: 'raw' as const, value: htmlIcon(iconIdentifier) }
+        : {
+            type: 'element' as const,
+            tagName: 'i',
+            properties: {
+              class: 'shiki-icon-highlight',
+              style: `--shiki-icon-url: url(${iconUrl})`
+            },
+            children: []
+          }
+
+      // Prepend the icon to the span content
+      if (hast.children) {
+        hast.children.unshift(iconElement)
+      }
+    }
+  }
+}

package/app/workers/prettier.js

@@ -1,9 +1,18 @@
-/* eslint-disable no-undef */
+let _prettier
+let _plugins
+
 self.onmessage = async function (event) {
-  self.postMessage({
-    uid: event.data.uid,
-    message: await handleMessage(event.data.message)
-  })
+  try {
+    self.postMessage({
+      uid: event.data.uid,
+      message: await handleMessage(event.data.message)
+    })
+  } catch (error) {
+    self.postMessage({
+      uid: event.data.uid,
+      error: error.message || String(error)
+    })
+  }
 }
 
 function handleMessage(message) {
@@ -14,23 +23,23 @@ function handleMessage(message) {
 }
 
 async function handleFormatMessage(message) {
-  if (!globalThis.prettier) {
-    await Promise.all([
-      import('https://cdn.jsdelivr.net/npm/prettier@3.7.4/standalone.js'),
-      import('https://cdn.jsdelivr.net/npm/prettier@3.7.4/plugins/babel.js'),
-      import('https://cdn.jsdelivr.net/npm/prettier@3.7.4/plugins/estree.js'),
-      import('https://cdn.jsdelivr.net/npm/prettier@3.7.4/plugins/html.js'),
-      import('https://cdn.jsdelivr.net/npm/prettier@3.7.4/plugins/markdown.js'),
-      import('https://cdn.jsdelivr.net/npm/prettier@3.7.4/plugins/typescript.js')
+  if (!_prettier) {
+    const [prettierModule, ...plugins] = await Promise.all([
+      import('https://cdn.jsdelivr.net/npm/prettier@3.7.4/standalone.mjs'),
+      import('https://cdn.jsdelivr.net/npm/prettier@3.7.4/plugins/babel.mjs'),
+      import('https://cdn.jsdelivr.net/npm/prettier@3.7.4/plugins/estree.mjs'),
+      import('https://cdn.jsdelivr.net/npm/prettier@3.7.4/plugins/html.mjs'),
+      import('https://cdn.jsdelivr.net/npm/prettier@3.7.4/plugins/markdown.mjs'),
+      import('https://cdn.jsdelivr.net/npm/prettier@3.7.4/plugins/typescript.mjs')
     ])
+    _prettier = prettierModule
+    _plugins = plugins
   }
 
   const { options, source } = message
-  const formatted = await prettier.format(source, {
+  return _prettier.format(source, {
     parser: 'markdown',
-    plugins: prettierPlugins,
+    plugins: _plugins,
     ...options
   })
-
-  return formatted
 }

package/modules/ai-chat/index.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs'
-import { join } from 'node:path'
+import { join } from 'pathe'
 import {
   addComponent,
   addComponentsDir,

package/modules/component-example.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import fsp from 'node:fs/promises'
-import { dirname, join } from 'pathe'
-import { defineNuxtModule, addTemplate, addServerHandler, createResolver } from '@nuxt/kit'
+import { join } from 'pathe'
+import { defineNuxtModule, addServerHandler, createResolver } from '@nuxt/kit'
 
 export default defineNuxtModule({
   meta: {
@@ -11,13 +11,20 @@ export default defineNuxtModule({
     const resolver = createResolver(import.meta.url)
     let _configResolved: any
     let components: Record<string, any>
-    const outputPath = join(nuxt.options.buildDir, 'component-example')
+    const outputDir = join(nuxt.options.buildDir, 'component-examples')
+
+    async function ensureOutputDir() {
+      if (!existsSync(outputDir)) {
+        await fsp.mkdir(outputDir, { recursive: true })
+      }
+    }
 
     async function stubOutput() {
-      if (existsSync(outputPath + '.mjs')) {
-        return
+      await ensureOutputDir()
+      const indexPath = join(outputDir, '_index.json')
+      if (!existsSync(indexPath)) {
+        await fsp.writeFile(indexPath, '[]', 'utf-8')
       }
-      await updateOutput('export default {}')
     }
 
     async function fetchComponent(component: string | any) {
@@ -46,20 +53,26 @@ export default defineNuxtModule({
         pascalName: component.pascalName
       }
     }
-    const getStringifiedComponents = () => JSON.stringify(components, null, 2)
 
-    const getVirtualModuleContent = () =>
-      `export default ${getStringifiedComponents()}`
+    async function writeComponentFile(name: string) {
+      const comp = components[name]
+      if (!comp?.code) return
+      await fsp.writeFile(
+        join(outputDir, `${name}.json`),
+        JSON.stringify({ code: comp.code, filePath: comp.filePath, pascalName: comp.pascalName }),
+        'utf-8'
+      )
+    }
+
+    async function writeIndex() {
+      const names = Object.keys(components).filter(k => components[k]?.code)
+      await fsp.writeFile(join(outputDir, '_index.json'), JSON.stringify(names), 'utf-8')
+    }
 
-    async function updateOutput(content?: string) {
-      const path = outputPath + '.mjs'
-      if (!existsSync(dirname(path))) {
-        await fsp.mkdir(dirname(path), { recursive: true })
-      }
-      if (existsSync(path)) {
-        await fsp.unlink(path)
-      }
-      await fsp.writeFile(path, content || getVirtualModuleContent(), 'utf-8')
+    async function updateOutput() {
+      await ensureOutputDir()
+      await Promise.all(Object.keys(components).map(writeComponentFile))
+      await writeIndex()
     }
 
     async function fetchComponents() {
@@ -76,12 +89,6 @@ export default defineNuxtModule({
       await stubOutput()
     })
 
-    addTemplate({
-      filename: 'component-example.mjs',
-      getContents: () => 'export default {}',
-      write: true
-    })
-
     nuxt.hook('vite:extend', (vite: any) => {
       vite.config.plugins = vite.config.plugins || []
       vite.config.plugins.push({
@@ -104,19 +111,47 @@ export default defineNuxtModule({
             )
           ) {
             await fetchComponent(file)
-            await updateOutput()
+            const entry = Object.entries(components).find(
+              ([, comp]: any) => comp.filePath === file
+            )
+            if (entry) {
+              await ensureOutputDir()
+              await writeComponentFile(entry[0])
+              await writeIndex()
+            }
           }
         }
       })
     })
 
     nuxt.hook('nitro:config', (nitroConfig) => {
+      nitroConfig.serverAssets = nitroConfig.serverAssets || []
+      nitroConfig.serverAssets.push({
+        baseName: 'component-examples',
+        dir: outputDir
+      })
+
       nitroConfig.virtual = nitroConfig.virtual || {}
-      nitroConfig.virtual['#component-example/nitro'] = () =>
-        readFileSync(
-          join(nuxt.options.buildDir, '/component-example.mjs'),
-          'utf-8'
-        )
+      nitroConfig.virtual['#component-example/nitro'] = () => {
+        const indexPath = join(outputDir, '_index.json')
+        const names: string[] = existsSync(indexPath)
+          ? JSON.parse(readFileSync(indexPath, 'utf-8'))
+          : []
+
+        return `import { useStorage } from '#imports'
+
+const names = ${JSON.stringify(names)}
+const _storage = () => useStorage('assets:component-examples')
+
+export async function getComponentExample(name) {
+  return await _storage().getItem(name + '.json')
+}
+
+export async function listComponentExamples() {
+  return names
+}
+`
+      }
     })
 
     addServerHandler({

package/modules/config.ts

@@ -1,9 +1,27 @@
+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'
@@ -31,7 +49,6 @@ export default defineNuxtModule({
       domain: url || 'https://example.com',
       title: siteName,
       description: meta.description || '',
-      contentRawMarkdown: false as const,
       full: {
         title: siteName,
         description: meta.description || ''
@@ -73,5 +90,11 @@ export default defineNuxtModule({
         ...createComponentMetaExcludeFilters(resolve, dir, layerPath, userInclude)
       ]
     })
+
+    // Load mdc.config from all layers
+    const mdcConfigSources = getMdcConfigSources(nuxt)
+    if (mdcConfigSources.length > 0) {
+      await nuxt.callHook('mdc:configSources', mdcConfigSources)
+    }
   }
 })

package/modules/css.ts

@@ -1,6 +1,6 @@
 import { addTemplate, defineNuxtModule } from '@nuxt/kit'
 import { fileURLToPath } from 'node:url'
-import { dirname, join } from 'node:path'
+import { dirname, join } from 'pathe'
 import { joinURL } from 'ufo'
 import { resolveModulePath } from 'exsolve'
 

package/nuxt.config.ts

@@ -1,8 +1,21 @@
 import { defineNuxtConfig } from 'nuxt/config'
 import pkg from './package.json'
+import { createResolver, useNuxt } from '@nuxt/kit'
+import { join } from 'pathe'
+
+const { resolve } = createResolver(import.meta.url)
 
 export default defineNuxtConfig({
   modules: [
+    () => {
+      const nuxt = useNuxt()
+      nuxt.options.icon ||= {}
+      nuxt.options.icon.customCollections ||= []
+      nuxt.options.icon.customCollections.push({
+        prefix: 'custom',
+        dir: join(nuxt.options.srcDir, 'assets/icons')
+      })
+    },
     '@nuxt/ui',
     '@nuxt/content',
     '@nuxt/image',
@@ -24,6 +37,7 @@ export default defineNuxtConfig({
   },
 
   content: {
+    experimental: { sqliteConnector: 'native' },
     build: {
       markdown: {
         highlight: {
@@ -46,6 +60,15 @@ export default defineNuxtConfig({
     }
   },
 
+  ui: {
+    theme: {
+      colors: ['primary', 'secondary', 'info', 'success', 'warning', 'error', 'important']
+    },
+    experimental: {
+      componentDetection: true
+    }
+  },
+
   runtimeConfig: {
     public: {
       version: pkg.version
@@ -61,7 +84,7 @@ export default defineNuxtConfig({
     }
   },
 
-  compatibilityDate: 'latest',
+  compatibilityDate: '2026-01-14',
 
   nitro: {
     prerender: {
@@ -143,7 +166,22 @@ export default defineNuxtConfig({
   },
 
   icon: {
-    provider: 'iconify'
+    customCollections: [
+      {
+        prefix: 'custom',
+        dir: resolve('./app/assets/icons')
+      }
+    ],
+    clientBundle: {
+      scan: true,
+      includeCustomCollections: true
+    }
+  },
+
+  llms: {
+    // Must be defined before @nuxt/content setup,
+    // otherwise Content LLMS module will overwrite it in modules:done.
+    contentRawMarkdown: false
   },
 
   ogImage: {

package/nuxt.schema.ts

@@ -315,7 +315,7 @@ export default defineNuxtSchema({
     aiChat: group({
       title: 'AI Chat',
       description: 'AI 聊天助手配置',
-      icon: 'i-lucide-sparkles',
+      icon: 'i-custom-ai',
       fields: {
         floatingInput: field({
           type: 'boolean',
@@ -440,7 +440,7 @@ export default defineNuxtSchema({
               type: 'string',
               title: '触发按钮',
               description: 'AI 聊天面板触发按钮的提示文本',
-              icon: 'i-lucide-sparkles',
+              icon: 'i-custom-ai',
               default: '与 AI 聊天'
             }),
             streaming: field({
@@ -483,8 +483,8 @@ export default defineNuxtSchema({
               type: 'string',
               title: '触发图标',
               description: 'AI 聊天触发按钮的图标',
-              icon: 'i-lucide-sparkles',
-              default: 'i-lucide-sparkles'
+              icon: 'i-custom-ai',
+              default: 'i-custom-ai'
             }),
             explain: field({
               type: 'string',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@movk/nuxt-docs",
   "type": "module",
-  "version": "1.13.1",
+  "version": "1.14.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>",
@@ -39,36 +39,35 @@
     "README.md"
   ],
   "dependencies": {
-    "@ai-sdk/gateway": "^3.0.55",
-    "@ai-sdk/mcp": "^1.0.21",
-    "@ai-sdk/vue": "^3.0.99",
-    "@iconify-json/lucide": "^1.2.94",
-    "@iconify-json/simple-icons": "^1.2.71",
+    "@ai-sdk/gateway": "^3.0.66",
+    "@ai-sdk/mcp": "^1.0.25",
+    "@ai-sdk/vue": "^3.0.116",
+    "@iconify-json/lucide": "^1.2.95",
+    "@iconify-json/simple-icons": "^1.2.72",
     "@iconify-json/vscode-icons": "^1.2.44",
-    "@movk/core": "^1.1.0",
+    "@movk/core": "^1.2.0",
     "@nuxt/a11y": "^1.0.0-alpha.1",
-    "@nuxt/content": "^3.11.2",
+    "@nuxt/content": "^3.12.0",
     "@nuxt/image": "^2.0.0",
     "@nuxt/kit": "^4.3.1",
-    "@nuxt/ui": "^4.5.0",
+    "@nuxt/ui": "^4.5.1",
     "@nuxtjs/mcp-toolkit": "^0.7.0",
-    "@nuxtjs/mdc": "^0.20.1",
-    "@nuxtjs/robots": "^5.7.0",
+    "@nuxtjs/mdc": "^0.20.2",
+    "@nuxtjs/robots": "^5.7.1",
     "@octokit/rest": "^22.0.1",
     "@openrouter/ai-sdk-provider": "^2.2.3",
-    "@shikijs/core": "^3.23.0",
-    "@shikijs/engine-javascript": "^3.23.0",
-    "@shikijs/langs": "^3.23.0",
-    "@shikijs/themes": "^3.23.0",
+    "@shikijs/core": "^4.0.1",
+    "@shikijs/engine-javascript": "^4.0.1",
+    "@shikijs/langs": "^4.0.1",
+    "@shikijs/themes": "^4.0.1",
     "@vercel/analytics": "^1.6.1",
     "@vercel/speed-insights": "^1.3.1",
     "@vueuse/core": "^14.2.1",
     "@vueuse/nuxt": "^14.2.1",
-    "ai": "^6.0.99",
+    "ai": "^6.0.111",
     "defu": "^6.1.4",
     "exsolve": "^1.0.8",
     "git-url-parse": "^16.1.0",
-    "minimark": "^1.0.0",
     "motion-v": "^2.0.0",
     "nuxt": "^4.3.1",
     "nuxt-component-meta": "^0.17.2",
@@ -79,6 +78,7 @@
     "pkg-types": "^2.3.0",
     "prettier": "^3.8.1",
     "scule": "^1.3.0",
+    "shiki-transformer-color-highlight": "^1.1.0",
     "shiki-stream": "^0.1.4",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "^4.2.1",

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

@@ -1,17 +1,17 @@
 import { defineEventHandler, createError, appendHeader } from 'h3'
 import { pascalCase } from 'scule'
 // @ts-expect-error - no types available
-import components from '#component-example/nitro'
+import { getComponentExample } from '#component-example/nitro'
 
-export default defineEventHandler((event) => {
+export default defineEventHandler(async (event) => {
   appendHeader(event, 'Access-Control-Allow-Origin', '*')
   const componentName = (event.context.params?.['component?'] || '').replace(/\.json$/, '')
   if (componentName) {
-    const component = components[pascalCase(componentName)]
+    const component = await getComponentExample(pascalCase(componentName))
     if (!component) {
       throw createError({
-        statusText: 'Example not found!',
-        status: 404
+        statusMessage: 'Example not found!',
+        statusCode: 404
       })
     }
     return component

package/server/api/github/{commits.get.ts → commits.json.get.ts}

@@ -24,20 +24,23 @@ export default defineCachedEventHandler(async (event) => {
     })
   }
 
-  const octokit = new Octokit({ auth: process.env.NUXT_GITHUB_TOKEN })
+  const octokit = new Octokit({
+    auth: process.env.NUXT_GITHUB_TOKEN,
+    request: { timeout: 10_000 }
+  })
 
   const allCommits = await Promise.all(
     paths.map(path =>
-      octokit.paginate(octokit.rest.repos.listCommits, {
+      octokit.rest.repos.listCommits({
         sha: github.branch,
         owner: github.owner,
         repo: github.name,
         path,
         since: github.since,
-        per_page: github.per_page,
+        per_page: github.per_page || 100,
         until: github.until,
         author
-      })
+      }).then(res => res.data).catch(() => [])
     )
   )
 

package/server/api/github/{last-commit.get.ts → last-commit.json.get.ts}

@@ -22,16 +22,19 @@ export default defineCachedEventHandler(async (event) => {
     })
   }
 
-  const octokit = new Octokit({ auth: process.env.NUXT_GITHUB_TOKEN })
+  const octokit = new Octokit({
+    auth: process.env.NUXT_GITHUB_TOKEN,
+    request: { timeout: 10_000 }
+  })
 
   try {
-    const { data: commits } = await octokit.rest.repos.listCommits({
+    const commits = await octokit.rest.repos.listCommits({
       sha: github.branch,
       owner: github.owner,
       repo: github.name,
       path,
       per_page: 1
-    })
+    }).then(res => res.data).catch(() => [])
 
     if (!commits.length) {
       return null
@@ -54,16 +57,16 @@ export default defineCachedEventHandler(async (event) => {
         // 从 squash commit message 中提取 PR 编号 (#166)
         const prMatch = commit.commit.message.match(/#(\d+)/)
         if (prMatch?.[1]) {
-          const { data: prData } = await octokit.rest.pulls.get({
+          const prData = await octokit.rest.pulls.get({
             owner: github.owner,
             repo: github.name,
             pull_number: Number.parseInt(prMatch[1])
-          })
+          }).then(res => res.data).catch(() => null)
 
-          authorLogin = prData.user?.login ?? authorLogin
-          authorAvatar = prData.user?.avatar_url ?? authorAvatar
-          authorName = prData.user?.name || authorLogin
-          commitUrl = prData.html_url
+          authorLogin = prData?.user?.login ?? authorLogin
+          authorAvatar = prData?.user?.avatar_url ?? authorAvatar
+          authorName = prData?.user?.name || authorLogin
+          commitUrl = prData?.html_url ?? commitUrl
         }
       } catch {
         // 获取 PR 信息失败时忽略，使用原始提交者信息

package/server/api/github/releases.json.get.ts

@@ -16,10 +16,10 @@ export default defineCachedEventHandler(async () => {
 
   const octokit = new Octokit({ auth: process.env.NUXT_GITHUB_TOKEN })
 
-  const { data: releases } = await octokit.rest.repos.listReleases({
+  const releases = await octokit.rest.repos.listReleases({
     owner: github.owner,
     repo: github.name
-  })
+  }).then(res => res.data).catch(() => [])
 
   return releases
 }, {

package/server/mcp/resources/documentation-pages.ts

@@ -0,0 +1,26 @@
+import { queryCollection } from '@nuxt/content/server'
+
+export default defineMcpResource({
+  uri: 'resource://docs/documentation-pages',
+  description: '所有可用文档页面的完整列表',
+  cache: '1h',
+  async handler(uri: URL) {
+    const event = useEvent()
+
+    const pages = await queryCollection(event, 'docs').all()
+
+    const result = pages.map(doc => ({
+      title: doc.title,
+      description: doc.description,
+      path: doc.path
+    }))
+
+    return {
+      contents: [{
+        uri: uri.toString(),
+        mimeType: 'application/json',
+        text: JSON.stringify(result, null, 2)
+      }]
+    }
+  }
+})