@movk/nuxt-docs 1.9.0 → 1.11.0

package/README.md

@@ -83,37 +83,14 @@ pnpm dev
 在现有 Nuxt 项目中使用 Movk Nuxt Docs 作为 layer：
 
 ```bash [Terminal]
-# 安装依赖
-pnpm add @movk/nuxt-docs better-sqlite3
-```
-
-在 CSS 中导入 Tailwind CSS 和 Nuxt UI
-
-```css [app/assets/css/main.css]
-@import 'tailwindcss';
-@import '@nuxt/ui';
+pnpm add @movk/nuxt-docs better-sqlite3 tailwindcss
 ```
 
 在 `nuxt.config.ts` 中配置：
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
-  extends: ['@movk/nuxt-docs'],
-  css: ['~/assets/css/main.css'],
-  aiChat: {
-    model: 'mistral/devstral-2',
-    models: ['mistral/devstral-2', 'openrouter/qwen/qwen3-4b:free']
-  },
-  mcp: {
-    name: 'My Docs',
-    browserRedirect: '/docs'
-  },
-  llms: {
-    domain: 'https://your-domain.com',
-    title: 'My Docs',
-    description: '基于 Movk Nuxt Docs 构建的智能文档站点',
-    notes: ['Nuxt 4', '文档主题', 'TypeScript']
-  }
++  extends: ['@movk/nuxt-docs']
 })
 ```
 
@@ -126,18 +103,16 @@ export default defineNuxtConfig({
 ```bash
 my-docs/
 ├── app/
-│   ├── assets/css/main.css      # 全局样式
 │   └── composables/             # 自定义 Composables
 ├── content/                     # Markdown 内容
 │   ├── index.md                 # 首页
 │   └── docs/                    # 文档页面
 ├── public/                      # 静态资源
 ├── nuxt.config.ts               # Nuxt 配置
-├── app.config.ts                # 应用配置
-├── content.config.ts            # 内容配置
 ├── tsconfig.json                # TypeScript 配置
 ├── package.json                 # 依赖与脚本
-└── README.md                    # 项目说明
+├── .env.example                # 环境变量示例
+└── pnpm-workspace.yaml          # pnpm 工作区配置
 ```
 
 ### Monorepo 结构

package/app/assets/css/main.css

@@ -0,0 +1,40 @@
+@import "tailwindcss" theme(static) source("../../../..");
+@import "@nuxt/ui";
+
+@theme static {
+  --container-8xl: 90rem;
+
+  --font-sans: 'Public Sans', sans-serif;
+
+  --color-green-50: #EFFDF5;
+  --color-green-100: #D9FBE8;
+  --color-green-200: #B3F5D1;
+  --color-green-300: #75EDAE;
+  --color-green-400: #00DC82;
+  --color-green-500: #00C16A;
+  --color-green-600: #00A155;
+  --color-green-700: #007F45;
+  --color-green-800: #016538;
+  --color-green-900: #0A5331;
+  --color-green-950: #052E16;
+}
+
+:root {
+  --ui-container: var(--container-8xl);
+}
+
+/* Shiki icon highlight transformer styles */
+.shiki-icon-highlight {
+  display: inline-block;
+  width: 1.25em;
+  height: 1.25em;
+  vertical-align: -0.25em;
+  margin-right: 0.125em;
+  background-color: var(--ui-text-highlighted);
+  -webkit-mask-repeat: no-repeat;
+  mask-repeat: no-repeat;
+  -webkit-mask-size: 100% 100%;
+  mask-size: 100% 100%;
+  -webkit-mask-image: var(--shiki-icon-url);
+  mask-image: var(--shiki-icon-url);
+}

package/app/mdc.config.ts

@@ -1,11 +1,9 @@
 import { defineConfig } from '@nuxtjs/mdc/config'
-import { transformerColorHighlight } from 'shiki-transformer-color-highlight'
 import { transformerIconHighlight } from './utils/shiki-transformer-icon-highlight'
 
 export default defineConfig({
   shiki: {
     transformers: [
-      transformerColorHighlight(),
       transformerIconHighlight()
     ]
   }

package/app/templates/releases.vue

@@ -21,32 +21,32 @@ defineOgImageComponent('Nuxt', {
   description
 })
 
-const { data: versions } = await useFetch(page.value.releases || '', {
-  server: false,
-  transform: (data: {
-    releases: {
-      name?: string
-      tag: string
-      publishedAt: string
-      markdown: string
-    }[]
-  }) => {
-    return data.releases.map(release => ({
-      tag: release.tag,
-      title: release.name || release.tag,
-      date: release.publishedAt,
-      markdown: release.markdown
-    }))
-  }
-})
+const { data: versions } = page.value.releases
+  ? await useFetch(page.value.releases, {
+      server: false,
+      transform: (data: {
+        releases: {
+          name?: string
+          tag: string
+          publishedAt: string
+          markdown: string
+        }[]
+      }) => data.releases.map(release => ({
+        tag: release.tag,
+        title: release.name || release.tag,
+        date: release.publishedAt,
+        markdown: release.markdown
+      }))
+    })
+  : { data: ref(null) }
 </script>
 
 <template>
   <main v-if="page">
     <UPageHero
-      :title="page.hero.title"
-      :description="page.hero.description"
-      :links="(page.hero.links as ButtonProps[]) || []"
+      :title="page.hero?.title || page.title"
+      :description="page.hero?.description || page.description"
+      :links="(page.hero?.links as ButtonProps[]) || []"
       class="md:border-b border-default"
       :ui="{ container: 'relative py-10 sm:py-16 lg:py-24' }"
     >
@@ -61,8 +61,11 @@ const { data: versions } = await useFetch(page.value.releases || '', {
 
     <UPageSection :ui="{ container: 'py-0!' }">
       <div class="py-4 md:py-8 lg:py-16 md:border-x border-default">
-        <UContainer class="max-w-5xl">
+        <UContainer class="flex flex-col max-w-5xl gap-y-8 sm:gap-y-12 lg:gap-y-16">
+          <ContentRenderer v-if="page.body" :value="page" />
+
           <UChangelogVersions
+            v-if="versions?.length"
             as="main"
             :indicator-motion="false"
             :ui="{

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

@@ -1,4 +1,3 @@
-/** copy from https://github.com/nuxt/ui/blob/v4/docs/app/utils/shiki-transformer-icon-highlight.ts */
 import type { ShikiTransformer } from 'shiki'
 
 export interface TransformerIconHighlightOptions {

package/content.config.ts

@@ -67,8 +67,8 @@ export default defineContentConfig({
       schema: z.object({
         title: z.string(),
         description: z.string(),
-        releases: z.string(),
-        hero: PageHero
+        releases: z.string().optional(),
+        hero: PageHero.optional()
       })
     })
   }

package/modules/css.ts

@@ -1,51 +1,36 @@
-import { addTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'
+import { addTemplate, defineNuxtModule } from '@nuxt/kit'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
 import { joinURL } from 'ufo'
+import { resolveModulePath } from 'exsolve'
 
 export default defineNuxtModule({
   meta: {
     name: 'css'
   },
-  async setup(_options, nuxt) {
-    const dir = nuxt.options.rootDir
-    const { resolve } = createResolver(import.meta.url)
+  setup(_options, nuxt) {
+    const currentDir = dirname(fileURLToPath(import.meta.url))
+    const mainCssPath = join(currentDir, '../app/assets/css/main.css')
+
+    nuxt.options.css ||= []
+    nuxt.options.css.unshift(mainCssPath)
 
-    const layerDir = resolve('../app')
-    const aiChatDir = resolve('../modules/ai-chat')
+    const dir = nuxt.options.rootDir
 
     const contentDir = joinURL(dir, 'content')
+    const uiPath = resolveModulePath('@nuxt/ui', { from: import.meta.url, conditions: ['style'] })
+    const tailwindPath = resolveModulePath('tailwindcss', { from: import.meta.url, conditions: ['style'] })
 
     const cssTemplate = addTemplate({
       filename: 'movk-nuxt-docs.css',
       getContents: () => {
-        return `@import "tailwindcss";
-@import "tailwindcss/theme.css" layer(theme) theme(static);
-@import "@nuxt/ui";
-
-@source "${contentDir.replace(/\\/g, '/')}/**/*";
-@source "${layerDir.replace(/\\/g, '/')}/**/*";
-@source "${aiChatDir.replace(/\\/g, '/')}/**/*";
-@source "../../app.config.ts";
+        return `@import ${JSON.stringify(tailwindPath)};
+@import ${JSON.stringify(uiPath)};
 
-/* Shiki icon highlight transformer styles */
-.shiki-icon-highlight {
-  display: inline-block;
-  width: 1.25em;
-  height: 1.25em;
-  vertical-align: -0.25em;
-  margin-right: 0.125em;
-  background-color: var(--ui-text-highlighted);
-  -webkit-mask-repeat: no-repeat;
-  mask-repeat: no-repeat;
-  -webkit-mask-size: 100% 100%;
-  mask-size: 100% 100%;
-  -webkit-mask-image: var(--shiki-icon-url);
-  mask-image: var(--shiki-icon-url);
-}`
+@source "${contentDir.replace(/\\/g, '/')}/**/*";`
       }
     })
 
-    if (Array.isArray(nuxt.options.css)) {
-      nuxt.options.css.unshift(cssTemplate.dst)
-    }
+    nuxt.options.css.unshift(cssTemplate.dst)
   }
 })

package/modules/md-rewrite.ts

@@ -1,4 +1,4 @@
-import { defineNuxtModule } from 'nuxt/kit'
+import { defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule((_options, nuxt) => {
   nuxt.hooks.hook('nitro:init', (nitro) => {

package/nuxt.config.ts

@@ -1,12 +1,17 @@
-import { createResolver, extendViteConfig } from '@nuxt/kit'
 import { defineNuxtConfig } from 'nuxt/config'
 import pkg from './package.json'
 
-const { resolve } = createResolver(import.meta.url)
+// WASM runtime imports that Rollup should not attempt to resolve
+const WASM_EXTERNALS = ['env', 'wasi_snapshot_preview1']
+
+function mergeExternals(existing: unknown, additions: string[]): string[] {
+  if (Array.isArray(existing)) return [...existing, ...additions]
+  if (typeof existing === 'string') return [existing, ...additions]
+  return additions
+}
 
 export default defineNuxtConfig({
   modules: [
-    resolve('./modules/config'),
     '@nuxt/ui',
     '@nuxt/content',
     '@nuxt/image',
@@ -16,30 +21,16 @@ export default defineNuxtConfig({
     'nuxt-component-meta',
     'nuxt-llms',
     'nuxt-og-image',
-    'motion-v/nuxt',
-    () => {
-      extendViteConfig((config) => {
-        config.optimizeDeps ||= {}
-        config.optimizeDeps.include ||= []
-        config.optimizeDeps.include.push(
-          '@nuxt/content > slugify',
-          'extend',
-          '@ai-sdk/gateway > @vercel/oidc',
-          'mermaid',
-          'dompurify'
-        )
-        config.optimizeDeps.include = config.optimizeDeps.include
-          .map(id => id.replace(/^@nuxt\/content > /, '@movk/nuxt-docs > @nuxt/content > '))
-      })
-    }
+    'motion-v/nuxt'
   ],
+
   app: {
     rootAttrs: {
       'data-vaul-drawer-wrapper': '',
       'class': 'bg-default'
     }
   },
-  // @ts-ignore - content 配置的类型定义在运行时才能正确解析
+
   content: {
     build: {
       markdown: {
@@ -56,22 +47,20 @@ export default defineNuxtConfig({
       }
     }
   },
+
   mdc: {
     highlight: {
       noApiRoute: false
     }
   },
+
   runtimeConfig: {
     public: {
       version: pkg.version
     }
   },
-  routeRules: {
-    '/llms.txt': { isr: true },
-    '/llms-full.txt': { isr: true }
-  },
+
   experimental: {
-    typescriptPlugin: true,
     asyncContext: true,
     defaults: {
       nuxtLink: {
@@ -79,7 +68,9 @@ export default defineNuxtConfig({
       }
     }
   },
+
   compatibilityDate: 'latest',
+
   nitro: {
     prerender: {
       crawlLinks: true,
@@ -87,9 +78,51 @@ export default defineNuxtConfig({
       autoSubfolderIndex: false
     }
   },
+
+  hooks: {
+    'vite:extendConfig': async (config) => {
+      // Rewrite optimizeDeps paths for layer architecture
+      const include = config.optimizeDeps?.include
+      if (!include) return
+
+      const layerPkgs = /^(?:@nuxt\/content|@nuxtjs\/mdc|@nuxt\/a11y) > /
+      include.forEach((id, i) => {
+        if (layerPkgs.test(id)) include[i] = `@movk/nuxt-docs > ${id}`
+      })
+
+      include.push(
+        '@movk/nuxt-docs > @nuxt/content > slugify',
+        '@movk/nuxt-docs > @ai-sdk/gateway > @vercel/oidc'
+      )
+
+      // WASM plugin support for Shiki
+      const [wasm, topLevelAwait] = await Promise.all([
+        import('vite-plugin-wasm'),
+        import('vite-plugin-top-level-await')
+      ])
+      config.plugins!.push(wasm.default(), topLevelAwait.default())
+
+      const build = config.build || ((config as any).build = {})
+      build.rollupOptions ??= {}
+      build.rollupOptions.external = mergeExternals(
+        build.rollupOptions.external,
+        WASM_EXTERNALS
+      )
+    },
+
+    'nitro:config': (nitroConfig) => {
+      nitroConfig.rollupConfig ??= {}
+      nitroConfig.rollupConfig.external = mergeExternals(
+        nitroConfig.rollupConfig.external,
+        WASM_EXTERNALS
+      )
+    }
+  },
+
   a11y: {
     logIssues: false
   },
+
   componentMeta: {
     metaFields: {
       type: false,
@@ -110,6 +143,7 @@ export default defineNuxtConfig({
       'nuxt-og-image'
     ]
   },
+
   fonts: {
     families: [
       { name: 'Public Sans', provider: 'google', global: true },
@@ -121,18 +155,16 @@ export default defineNuxtConfig({
       { name: 'Raleway', provider: 'google', global: true }
     ]
   },
+
   icon: {
     provider: 'iconify'
   },
+
   ogImage: {
     zeroRuntime: true,
-    googleFontMirror: 'fonts.loli.net',
     fonts: [
       'Noto+Sans+SC:400',
-      'Noto+Sans+SC:500',
-      'Noto+Sans+SC:700',
-      'Inter:400',
-      'Inter:700'
+      'Inter:400'
     ]
   }
 })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@movk/nuxt-docs",
   "type": "module",
-  "version": "1.9.0",
+  "version": "1.11.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>",
@@ -14,7 +14,8 @@
   "main": "./nuxt.config.ts",
   "peerDependencies": {
     "better-sqlite3": "12.x",
-    "nuxt": "4.x"
+    "nuxt": "4.x",
+    "tailwindcss": "4.x"
   },
   "files": [
     "app",
@@ -28,13 +29,11 @@
     "README.md"
   ],
   "dependencies": {
-    "@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",
-    "@iconify-json/tabler": "^1.2.26",
+    "@ai-sdk/gateway": "^3.0.29",
+    "@ai-sdk/mcp": "^1.0.16",
+    "@ai-sdk/vue": "^3.0.64",
+    "@iconify-json/lucide": "^1.2.87",
+    "@iconify-json/simple-icons": "^1.2.68",
     "@iconify-json/vscode-icons": "^1.2.40",
     "@movk/core": "^1.1.0",
     "@nuxt/a11y": "^1.0.0-alpha.1",
@@ -43,19 +42,21 @@
     "@nuxt/kit": "^4.3.0",
     "@nuxt/ui": "^4.4.0",
     "@nuxtjs/mcp-toolkit": "^0.6.2",
+    "@nuxtjs/mdc": "^0.20.0",
     "@octokit/rest": "^22.0.1",
-    "@openrouter/ai-sdk-provider": "^2.0.0",
+    "@openrouter/ai-sdk-provider": "^2.1.1",
     "@vercel/analytics": "^1.6.1",
     "@vercel/speed-insights": "^1.3.1",
-    "@vueuse/core": "^14.1.0",
-    "@vueuse/nuxt": "^14.1.0",
-    "ai": "^6.0.48",
+    "@vueuse/core": "^14.2.0",
+    "@vueuse/nuxt": "^14.2.0",
+    "ai": "^6.0.64",
     "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",
+    "minimark": "^0.2.0",
+    "motion-v": "^1.10.2",
     "nuxt": "^4.3.0",
     "nuxt-component-meta": "^0.17.1",
     "nuxt-llms": "^0.2.0",
@@ -65,11 +66,14 @@
     "pkg-types": "^2.3.0",
     "prettier": "^3.8.1",
     "scule": "^1.3.0",
-    "shiki": "^3.21.0",
+    "shiki": "^3.22.0",
     "shiki-stream": "^0.1.4",
-    "shiki-transformer-color-highlight": "^1.0.0",
+    "tailwind-merge": "^3.4.0",
     "tailwindcss": "^4.1.18",
     "ufo": "^1.6.3",
+    "vue-component-meta": "^3.2.4",
+    "vite-plugin-top-level-await": "^1.6.0",
+    "vite-plugin-wasm": "^3.5.0",
     "zod": "^4.3.6"
   }
 }

package/server/plugins/llms.ts

@@ -6,9 +6,10 @@ export default defineNitroPlugin((nitroApp) => {
     await transformMDC(event, doc as any)
   })
 
+  // @ts-expect-error - no types available
   nitroApp.hooks.hook('llms:generate', (_, { sections }) => {
     // Move "Documentation Sets" to the end
-    const docSetIdx = sections.findIndex(s => s.title === 'Documentation Sets')
+    const docSetIdx = sections.findIndex((s: any) => s.title === 'Documentation Sets')
     if (docSetIdx !== -1) {
       const [docSet] = sections.splice(docSetIdx, 1)
       if (docSet) {

package/utils/component-meta.ts

@@ -3,10 +3,6 @@ import { join } from 'pathe'
 
 /**
  * 匹配组件是否符合用户定义的 include 模式
- * @param filePath 组件文件路径
- * @param pascalName 组件 PascalCase 名称
- * @param includePatterns 包含模式数组(字符串 glob、正则表达式或函数)
- * @returns 是否匹配
  */
 function matchesUserInclude(
   filePath: string,
@@ -35,9 +31,6 @@ function matchesUserInclude(
 
 /**
  * 检查组件是否为用户组件
- * @param filePath 组件文件路径
- * @param userComponentPaths 用户组件路径数组
- * @returns 是否为用户组件
  */
 export function isUserComponent(filePath: string, userComponentPaths: string[]): boolean {
   return userComponentPaths.some(path => filePath.startsWith(path))
@@ -45,11 +38,6 @@ export function isUserComponent(filePath: string, userComponentPaths: string[]):
 
 /**
  * 创建 component-meta exclude 过滤器
- * @param layerPath layer 路径
- * @param allowedComponents 允许的组件列表
- * @param userComponentPaths 用户组件路径数组
- * @param userInclude 用户定义的 include 模式
- * @returns exclude 过滤器数组
  */
 export function createComponentMetaExcludeFilters(
   resolve: Resolver['resolve'],