docus 5.8.1 → 5.10.0

package/modules/assistant/index.ts

@@ -1,4 +1,5 @@
 import { addComponent, addImports, addServerHandler, createResolver, defineNuxtModule, logger } from '@nuxt/kit'
+import { defu } from 'defu'
 
 export interface AssistantModuleOptions {
   /**
@@ -22,24 +23,33 @@ export interface AssistantModuleOptions {
 
 const log = logger.withTag('Docus')
 
+const defaults: Required<AssistantModuleOptions> = {
+  apiPath: '/__docus__/assistant',
+  mcpServer: '/mcp',
+  model: 'google/gemini-3-flash',
+}
+
 export default defineNuxtModule<AssistantModuleOptions>({
   meta: {
     name: 'assistant',
-    configKey: 'assistant',
   },
-  defaults: {
-    apiPath: '/__docus__/assistant',
-    mcpServer: '/mcp',
-    model: 'google/gemini-3-flash',
-  },
-  setup(options, nuxt) {
-    const hasApiKey = !!process.env.AI_GATEWAY_API_KEY
+  setup(_options, nuxt) {
+    const legacyOptions = nuxt.options.assistant
+    if (legacyOptions && Object.keys(legacyOptions).length > 0) {
+      log.warn('`assistant` top-level config is deprecated. Move it under `docus.assistant` in nuxt.config.ts')
+    }
+
+    const options = defu(nuxt.options.docus?.assistant, legacyOptions, defaults) as Required<AssistantModuleOptions>
+
+    const hasAiGatewayAuth = !!(
+      process.env.AI_GATEWAY_API_KEY || process.env.VERCEL_OIDC_TOKEN
+    )
 
     const { resolve } = createResolver(import.meta.url)
 
     nuxt.options.runtimeConfig.public.assistant = {
-      enabled: hasApiKey,
-      apiPath: options.apiPath!,
+      enabled: hasAiGatewayAuth,
+      apiPath: options.apiPath,
     }
 
     addImports([
@@ -60,23 +70,23 @@ export default defineNuxtModule<AssistantModuleOptions>({
     components.forEach(name =>
       addComponent({
         name,
-        filePath: hasApiKey
+        filePath: hasAiGatewayAuth
           ? resolve(`./runtime/components/${name}.vue`)
           : resolve('./runtime/components/AssistantChatDisabled.vue'),
       }),
     )
 
-    if (!hasApiKey) {
-      log.warn('AI assistant disabled: AI_GATEWAY_API_KEY not found')
+    if (!hasAiGatewayAuth) {
+      log.warn('AI assistant disabled: neither AI_GATEWAY_API_KEY nor VERCEL_OIDC_TOKEN found')
       return
     }
 
     nuxt.options.runtimeConfig.assistant = {
-      mcpServer: options.mcpServer!,
-      model: options.model!,
+      mcpServer: options.mcpServer,
+      model: options.model,
     }
 
-    const routePath = options.apiPath!.replace(/^\//, '')
+    const routePath = options.apiPath.replace(/^\//, '')
     addServerHandler({
       route: `/${routePath}`,
       handler: resolve('./runtime/server/api/search'),

package/modules/assistant/runtime/server/api/search.ts

@@ -37,6 +37,11 @@ function getSystemPrompt(siteName: string) {
 - Be concise, helpful, and direct
 - Guide users like a friendly expert would
 
+**Links and exploration:**
+- Tool results include a \`url\` for each page — prefer markdown links \`[label](url)\` so users can open the doc in one click
+- When it helps, add extra links (related pages, “read more”, side topics) — make the answer easy to dig into, not a wall of text
+- Stick to URLs from tool results (\`url\` / \`path\`) so links stay valid
+
 **FORMATTING RULES (CRITICAL):**
 - NEVER use markdown headings (#, ##, ###, etc.)
 - Use **bold text** for emphasis and section labels

package/modules/config.ts

@@ -58,13 +58,18 @@ export default defineNuxtModule({
       branch: getGitBranch(),
     })
 
+    const forcedColorMode = (nuxt.options.appConfig.docus as Record<string, unknown>)?.colorMode as string | undefined
+    if (forcedColorMode === 'light' || forcedColorMode === 'dark') {
+      nuxt.options.colorMode = defu({ preference: forcedColorMode, fallback: forcedColorMode }, nuxt.options.colorMode || {}) as typeof nuxt.options.colorMode
+    }
+
     /*
     ** I18N
     */
-    const typedNuxtOptions = nuxt.options as typeof nuxt.options & { i18n?: DocusI18nOptions }
+    const typedNuxtOptions = nuxt.options as typeof nuxt.options & { i18n?: false | DocusI18nOptions }
     const i18nOptions = typedNuxtOptions.i18n
 
-    if (i18nOptions?.locales) {
+    if (i18nOptions && typeof i18nOptions === 'object' && i18nOptions.locales) {
       const { resolve } = createResolver(import.meta.url)
 
       // Filter locales to only include existing ones

package/modules/css.ts

@@ -32,5 +32,17 @@ export default defineNuxtModule({
     if (Array.isArray(nuxt.options.css)) {
       nuxt.options.css.unshift(cssTemplate.dst)
     }
+
+    // Noisy Vite warnings
+    const sourcemapWarnIgnore = ['@tailwindcss/vite:generate:build', 'nuxt:module-preload-polyfill']
+    nuxt.hook('vite:extendConfig', (config) => {
+      const logger = config.customLogger
+      if (!logger) return
+      const originalWarn = logger.warn.bind(logger)
+      logger.warn = (msg, options) => {
+        if (sourcemapWarnIgnore.some(p => msg.includes(p))) return
+        originalWarn(msg, options)
+      }
+    })
   },
 })

package/modules/skills/index.ts

@@ -0,0 +1,158 @@
+import { addPrerenderRoutes, addServerHandler, createResolver, defineNuxtModule, logger } from '@nuxt/kit'
+import { defu } from 'defu'
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { NitroConfig } from 'nitropack'
+import { parse as parseYaml } from 'yaml'
+
+interface SkillEntry {
+  name: string
+  description: string
+  files: string[]
+}
+
+export interface SkillsModuleOptions {
+  dir?: string
+}
+
+const SKILL_NAME_REGEX = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
+const MAX_NAME_LENGTH = 64
+
+const log = logger.withTag('Docus')
+
+const defaults: Required<SkillsModuleOptions> = {
+  dir: 'skills',
+}
+
+export default defineNuxtModule<SkillsModuleOptions>({
+  meta: {
+    name: 'skills',
+  },
+  async setup(_inlineOptions, nuxt) {
+    const options = defu(nuxt.options.docus?.skills, defaults) as Required<SkillsModuleOptions>
+
+    const skillsDir = join(nuxt.options.rootDir, options.dir)
+    if (!existsSync(skillsDir)) return
+
+    const catalog = await scanSkills(skillsDir)
+    if (!catalog.length) return
+
+    log.info(`Found ${catalog.length} agent skill${catalog.length > 1 ? 's' : ''}: ${catalog.map(s => s.name).join(', ')}`)
+
+    nuxt.options.runtimeConfig.skills = { catalog }
+
+    const { resolve } = createResolver(import.meta.url)
+
+    const onNitroConfig = nuxt.hook as (name: 'nitro:config', cb: (nitroConfig: NitroConfig) => void) => void
+    onNitroConfig('nitro:config', (nitroConfig) => {
+      nitroConfig.serverAssets ||= []
+      nitroConfig.serverAssets.push({ baseName: 'skills', dir: skillsDir })
+    })
+
+    const prerenderRoutes = ['/.well-known/skills/index.json']
+    for (const skill of catalog) {
+      for (const file of skill.files) {
+        prerenderRoutes.push(`/.well-known/skills/${skill.name}/${file}`)
+      }
+    }
+    addPrerenderRoutes(prerenderRoutes)
+
+    addServerHandler({
+      route: '/.well-known/skills/index.json',
+      handler: resolve('./runtime/server/routes/skills-index'),
+    })
+
+    addServerHandler({
+      route: '/.well-known/skills/**',
+      handler: resolve('./runtime/server/routes/skills-files'),
+    })
+  },
+})
+
+function parseFrontmatter(content: string): { name?: string, description?: string } | null {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!match?.[1]) return null
+  try {
+    return parseYaml(match[1])
+  }
+  catch {
+    return null
+  }
+}
+
+function validateSkillName(name: string, dirName: string): boolean {
+  if (name.length > MAX_NAME_LENGTH) {
+    log.warn(`Skill "${name}" exceeds ${MAX_NAME_LENGTH} character limit`)
+    return false
+  }
+  if (!SKILL_NAME_REGEX.test(name) || name.includes('--')) {
+    log.warn(`Skill name "${name}" does not match the Agent Skills naming spec`)
+    return false
+  }
+  if (name !== dirName) {
+    log.warn(`Skill name "${name}" does not match directory name "${dirName}"`)
+    return false
+  }
+  return true
+}
+
+async function listFilesRecursively(dir: string, base: string = ''): Promise<string[]> {
+  const files: string[] = []
+  const entries = await readdir(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    const relPath = base ? `${base}/${entry.name}` : entry.name
+    if (entry.isDirectory()) {
+      files.push(...await listFilesRecursively(join(dir, entry.name), relPath))
+    }
+    else {
+      files.push(relPath)
+    }
+  }
+  return files
+}
+
+async function scanSkills(skillsDir: string): Promise<SkillEntry[]> {
+  const catalog: SkillEntry[] = []
+  const entries = await readdir(skillsDir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+
+    const skillDir = join(skillsDir, entry.name)
+    const skillMdPath = join(skillDir, 'SKILL.md')
+
+    if (!existsSync(skillMdPath)) continue
+
+    const content = await readFile(skillMdPath, 'utf-8')
+    const frontmatter = parseFrontmatter(content)
+
+    if (!frontmatter?.description) {
+      log.warn(`Skipping skill "${entry.name}": missing description in SKILL.md frontmatter`)
+      continue
+    }
+
+    const name = frontmatter.name || entry.name
+    if (!validateSkillName(name, entry.name)) continue
+
+    const allFiles = await listFilesRecursively(skillDir)
+    const files = allFiles.filter(f => !f.split('/').some(s => s.startsWith('.')))
+    const sortedFiles = ['SKILL.md', ...files.filter(f => f !== 'SKILL.md')]
+
+    catalog.push({
+      name,
+      description: frontmatter.description,
+      files: sortedFiles,
+    })
+  }
+
+  return catalog
+}
+
+declare module 'nuxt/schema' {
+  interface RuntimeConfig {
+    skills: {
+      catalog: SkillEntry[]
+    }
+  }
+}

package/modules/skills/runtime/server/routes/skills-files.ts

@@ -0,0 +1,49 @@
+const CONTENT_TYPES: Record<string, string> = {
+  '.md': 'text/markdown; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.yaml': 'text/yaml; charset=utf-8',
+  '.yml': 'text/yaml; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+  '.py': 'text/plain; charset=utf-8',
+  '.sh': 'text/plain; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.ts': 'text/plain; charset=utf-8',
+}
+
+function getContentType(path: string): string {
+  const ext = path.slice(path.lastIndexOf('.'))
+  return CONTENT_TYPES[ext] || 'application/octet-stream'
+}
+
+export default defineEventHandler(async (event) => {
+  const url = getRequestURL(event)
+  const prefix = '/.well-known/skills/'
+  const idx = url.pathname.indexOf(prefix)
+  if (idx === -1) {
+    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+  }
+
+  const filePath = decodeURIComponent(url.pathname.slice(idx + prefix.length))
+
+  if (!filePath || filePath.includes('..')) {
+    throw createError({ statusCode: 400, statusMessage: 'Bad Request' })
+  }
+
+  const { skills } = useRuntimeConfig(event)
+  const skillName = filePath.split('/')[0]
+  if (!skills.catalog.some((s: { name: string }) => s.name === skillName)) {
+    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+  }
+
+  const storage = useStorage('assets:skills')
+  const content = await storage.getItemRaw<string>(filePath)
+
+  if (!content) {
+    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+  }
+
+  setResponseHeader(event, 'content-type', getContentType(filePath))
+  setResponseHeader(event, 'cache-control', 'public, max-age=3600')
+
+  return content
+})

package/modules/skills/runtime/server/routes/skills-index.ts

@@ -0,0 +1,8 @@
+export default defineEventHandler((event) => {
+  const { skills } = useRuntimeConfig(event)
+
+  setResponseHeader(event, 'content-type', 'application/json')
+  setResponseHeader(event, 'cache-control', 'public, max-age=3600')
+
+  return { skills: skills.catalog }
+})

package/nuxt.config.ts

@@ -10,6 +10,7 @@ export default defineNuxtConfig({
     resolve('./modules/config'),
     resolve('./modules/routing'),
     resolve('./modules/markdown-rewrite'),
+    resolve('./modules/skills'),
     resolve('./modules/css'),
     () => {
       const nuxt = useNuxt()
@@ -38,9 +39,11 @@ export default defineNuxtConfig({
 
         // Fix @vercel/oidc ESM export issue (transitive dep of @ai-sdk/gateway)
         // Only needed when AI assistant is enabled.
-        if (process.env.AI_GATEWAY_API_KEY) {
+        if (process.env.AI_GATEWAY_API_KEY || process.env.VERCEL_OIDC_TOKEN) {
           config.optimizeDeps.include.push('@vercel/oidc')
-          config.optimizeDeps.include.map(id => id.replace(/^@vercel\/oidc$/, 'docus > @vercel/oidc'))
+          config.optimizeDeps.include = config.optimizeDeps.include.map(id =>
+            id.replace(/^@vercel\/oidc$/, 'docus > @vercel/oidc'),
+          )
         }
       })
     },
@@ -118,6 +121,9 @@ export default defineNuxtConfig({
     },
     provider: 'iconify',
   },
+  ogImage: {
+    zeroRuntime: true,
+  },
   robots: {
     groups: [
       {

package/nuxt.schema.ts

@@ -277,6 +277,28 @@ export default defineNuxtSchema({
         }),
       },
     }),
+    docus: group({
+      title: 'Docus',
+      description: 'Docus configuration.',
+      icon: 'i-lucide-settings',
+      fields: {
+        locale: field({
+          type: 'string',
+          title: 'Locale',
+          description: 'Default locale for single-language documentation.',
+          icon: 'i-lucide-languages',
+          default: 'en',
+        }),
+        colorMode: field({
+          type: 'string',
+          title: 'Color Mode',
+          description: 'Force a specific color mode. Leave empty for system preference with toggle.',
+          icon: 'i-lucide-monitor',
+          default: '',
+          required: ['', 'light', 'dark'],
+        }),
+      },
+    }),
     assistant: group({
       title: 'Assistant',
       description: 'Assistant configuration.',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docus",
   "description": "Nuxt layer for Docus documentation theme",
-  "version": "5.8.1",
+  "version": "5.10.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "repository": {
@@ -14,6 +14,7 @@
     "app",
     "i18n",
     "content.config.ts",
+    "index.d.ts",
     "modules",
     "nuxt.config.ts",
     "nuxt.schema.ts",
@@ -22,39 +23,41 @@
     "README.md"
   ],
   "dependencies": {
-    "@ai-sdk/gateway": "^3.0.66",
-    "@ai-sdk/mcp": "^1.0.25",
-    "@ai-sdk/vue": "3.0.116",
-    "@iconify-json/lucide": "^1.2.96",
-    "@iconify-json/simple-icons": "^1.2.73",
+    "@ai-sdk/gateway": "^3.0.83",
+    "@ai-sdk/mcp": "^1.0.30",
+    "@ai-sdk/vue": "3.0.141",
+    "@iconify-json/lucide": "^1.2.100",
+    "@iconify-json/simple-icons": "^1.2.75",
     "@iconify-json/vscode-icons": "^1.2.45",
     "@nuxt/content": "^3.12.0",
     "@nuxt/image": "^2.0.0",
-    "@nuxt/kit": "^4.3.1",
-    "@nuxt/ui": "^4.5.1",
-    "@nuxtjs/i18n": "^10.2.3",
-    "@nuxtjs/mcp-toolkit": "^0.7.0",
-    "@nuxtjs/mdc": "^0.20.2",
-    "@nuxtjs/robots": "^5.7.1",
+    "@nuxt/kit": "^4.4.2",
+    "@nuxt/ui": "^4.6.0",
+    "@nuxtjs/i18n": "^10.2.4",
+    "@nuxtjs/mcp-toolkit": "^0.13.2",
+    "@nuxtjs/mdc": "^0.21.0",
+    "@nuxtjs/robots": "^6.0.6",
+    "@shikijs/core": "^4.0.2",
+    "@shikijs/engine-javascript": "^4.0.2",
+    "@shikijs/langs": "^4.0.2",
+    "@shikijs/themes": "^4.0.2",
+    "@takumi-rs/core": "^0.73.1",
     "@vueuse/core": "^14.2.1",
-    "ai": "6.0.116",
+    "ai": "6.0.141",
     "defu": "^6.1.4",
     "exsolve": "^1.0.8",
     "git-url-parse": "^16.1.0",
-    "motion-v": "^1.10.3",
+    "motion-v": "^2.2.0",
     "nuxt-llms": "^0.2.0",
-    "nuxt-og-image": "^5.1.13",
+    "nuxt-og-image": "^6.3.1",
     "pkg-types": "^2.3.0",
     "scule": "^1.3.0",
-    "@shikijs/core": "^3.22.0",
-    "@shikijs/engine-javascript": "^3.22.0",
-    "@shikijs/langs": "^3.22.0",
-    "@shikijs/themes": "^3.22.0",
     "shiki-stream": "^0.1.4",
-    "tailwindcss": "^4.2.1",
+    "tailwindcss": "^4.2.2",
     "ufo": "^1.6.3",
+    "yaml": "^2.7.1",
     "zod": "^4.3.6",
-    "zod-to-json-schema": "^3.25.1"
+    "zod-to-json-schema": "^3.25.2"
   },
   "peerDependencies": {
     "better-sqlite3": "12.x",

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

@@ -17,9 +17,19 @@ WHEN NOT TO USE: If you don't know the exact path and need to search/explore, us
 
 WORKFLOW: This tool returns the complete page content including title, description, and full markdown. Use this when you need to provide detailed answers or code examples from specific documentation pages.
 `,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     path: z.string().describe('The page path from list-pages or provided by the user (e.g., /en/getting-started/installation)'),
   },
+  inputExamples: [
+    { path: '/en/getting-started/installation' },
+    { path: '/getting-started/introduction' },
+  ],
   cache: '1h',
   handler: async ({ path }) => {
     const event = useEvent()
@@ -38,21 +48,22 @@ WORKFLOW: This tool returns the complete page content including title, descripti
         .first()
 
       if (!page) {
-        return errorResult('Page not found')
+        throw createError({ statusCode: 404, message: 'Page not found' })
       }
 
       const content = await event.$fetch<string>(`/raw${path}.md`)
 
-      return jsonResult({
+      return {
         title: page.title,
         path: page.path,
         description: page.description,
         content,
         url: `${siteUrl}${page.path}`,
-      })
+      }
     }
-    catch {
-      return errorResult('Failed to get page')
+    catch (error) {
+      if ((error as { statusCode?: number }).statusCode === 404) throw error
+      throw createError({ statusCode: 500, message: 'Failed to get page' })
     }
   },
 })

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

@@ -23,9 +23,19 @@ OUTPUT: Returns a structured list with:
 - path: Exact path for use with get-page
 - description: Brief summary of page content
 - url: Full URL for reference`,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
-    locale: z.string().optional().describe('The locale to filter pages by'),
+    locale: z.string().optional().describe('The locale to filter pages by (e.g., "en", "fr")'),
   },
+  inputExamples: [
+    { locale: 'en' },
+    {},
+  ],
   cache: '1h',
   handler: async ({ locale }) => {
     const event = useEvent()
@@ -52,10 +62,10 @@ OUTPUT: Returns a structured list with:
         }),
       )
 
-      return jsonResult(allPages.flat())
+      return allPages.flat()
     }
     catch {
-      return errorResult('Failed to list pages')
+      throw createError({ statusCode: 500, message: 'Failed to list pages' })
     }
   },
 })

package/app/components/OgImage/OgImageDocs.vue

@@ -1,76 +0,0 @@
-<script lang="ts" setup>
-const props = withDefaults(defineProps<{ title?: string, description?: string, headline?: string }>(), {
-  title: 'title',
-  description: 'description',
-})
-
-const title = (props.title || '').slice(0, 60)
-const description = (props.description || '').slice(0, 200)
-</script>
-
-<template>
-  <div class="w-full h-full flex flex-col justify-center bg-neutral-900">
-    <svg
-      class="absolute right-0 top-0 opacity-50"
-      width="629"
-      height="593"
-      viewBox="0 0 629 593"
-      fill="none"
-      xmlns="http://www.w3.org/2000/svg"
-    >
-      <g filter="url(#filter0_f_199_94966)">
-        <path
-          d="M628.5 -578L639.334 -94.4223L806.598 -548.281L659.827 -87.387L965.396 -462.344L676.925 -74.0787L1087.69 -329.501L688.776 -55.9396L1160.22 -164.149L694.095 -34.9354L1175.13 15.7948L692.306 -13.3422L1130.8 190.83L683.602 6.50012L1032.04 341.989L668.927 22.4412L889.557 452.891L649.872 32.7537L718.78 511.519L628.5 36.32L538.22 511.519L607.128 32.7537L367.443 452.891L588.073 22.4412L224.955 341.989L573.398 6.50012L126.198 190.83L564.694 -13.3422L81.8734 15.7948L562.905 -34.9354L96.7839 -164.149L568.224 -55.9396L169.314 -329.501L580.075 -74.0787L291.604 -462.344L597.173 -87.387L450.402 -548.281L617.666 -94.4223L628.5 -578Z"
-          fill="white"
-        />
-      </g>
-      <defs>
-        <filter
-          id="filter0_f_199_94966"
-          x="0.873535"
-          y="-659"
-          width="1255.25"
-          height="1251.52"
-          filterUnits="userSpaceOnUse"
-          color-interpolation-filters="sRGB"
-        >
-          <feFlood
-            flood-opacity="0"
-            result="BackgroundImageFix"
-          />
-          <feBlend
-            mode="normal"
-            in="SourceGraphic"
-            in2="BackgroundImageFix"
-            result="shape"
-          />
-          <feGaussianBlur
-            stdDeviation="40.5"
-            result="effect1_foregroundBlur_199_94966"
-          />
-        </filter>
-      </defs>
-    </svg>
-
-    <div class="pl-[100px]">
-      <p
-        v-if="headline"
-        class="uppercase text-[24px] text-emerald-500 mb-4 font-semibold"
-      >
-        {{ headline }}
-      </p>
-      <h1
-        v-if="title"
-        class="m-0 text-[75px] font-semibold mb-4 text-white flex items-center"
-      >
-        <span>{{ title }}</span>
-      </h1>
-      <p
-        v-if="description"
-        class="text-[32px] text-neutral-300 leading-tight w-[700px]"
-      >
-        {{ description }}
-      </p>
-    </div>
-  </div>
-</template>