docus 5.10.0 → 5.11.0

package/app/app.config.ts

@@ -17,7 +17,7 @@ export default defineAppConfig({
     },
     contentToc: {
       defaultVariants: {
-        highlight: true,
+        highlightVariant: 'circuit',
       },
     },
     contentNavigation: {

package/app/components/docs/DocsPageHeaderLinks.vue

@@ -1,15 +1,20 @@
 <script setup lang="ts">
 import { useClipboard } from '@vueuse/core'
+import { joinURL, withTrailingSlash } from 'ufo'
 import { useRuntimeConfig } from '#imports'
 
 const route = useRoute()
 const toast = useToast()
-const appBaseURL = useRuntimeConfig().app?.baseURL || '/'
+const runtimeConfig = useRuntimeConfig()
+const appBaseURL = runtimeConfig.app?.baseURL || '/'
+const mcpRoute = (runtimeConfig.public.mcp as { route?: string } | undefined)?.route || '/mcp'
 
 const { copy, copied } = useClipboard()
 const { t } = useDocusI18n()
 
-const markdownLink = computed(() => `${window?.location?.origin}${appBaseURL}raw${route.path}.md`)
+const markdownLink = computed(() => `${window?.location?.origin}${withTrailingSlash(appBaseURL)}raw${route.path}.md`)
+const mcpServerUrl = computed(() => `${window?.location?.origin}${joinURL(appBaseURL, mcpRoute)}`)
+const mcpDeeplink = joinURL(mcpRoute, 'deeplink')
 const items = [
   [{
     label: t('docs.copy.link'),
@@ -41,7 +46,7 @@ const items = [
       label: 'Copy MCP Server URL',
       icon: 'i-lucide-link',
       onSelect() {
-        copy(`${window?.location?.origin}${appBaseURL}mcp`)
+        copy(mcpServerUrl.value)
         toast.add({
           title: 'Copied to clipboard',
           icon: 'i-lucide-check-circle',
@@ -52,7 +57,7 @@ const items = [
       label: 'Add MCP Server',
       icon: 'i-simple-icons:cursor',
       target: '_blank',
-      to: `/mcp/deeplink`,
+      to: mcpDeeplink,
     },
   ],
 ]

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

@@ -76,6 +76,7 @@ addPrerenderPath(`/raw${route.path}.md`)
   <UPage
     v-if="page"
     :key="`page-${shouldHideToc}`"
+    :ui="{ root: 'lg:grid-cols-12', center: 'lg:col-span-9', right: 'lg:col-span-3' }"
   >
     <UPageHeader
       :title="page.title"

package/app/plugins/i18n.ts

@@ -1,7 +1,7 @@
 import type { RouteLocationNormalized } from 'vue-router'
 import { consola } from 'consola'
 
-const log = consola.withTag('Docus')
+const log = consola.withTag('docus')
 
 // Lazy import functions for locale files (bundled but not eagerly loaded)
 const localeFiles = import.meta.glob<{ default: Record<string, unknown> }>('../../i18n/locales/*.json')

package/modules/assistant/index.ts

@@ -21,7 +21,7 @@ export interface AssistantModuleOptions {
   model?: string
 }
 
-const log = logger.withTag('Docus')
+const log = logger.withTag('docus')
 
 const defaults: Required<AssistantModuleOptions> = {
   apiPath: '/__docus__/assistant',
@@ -77,7 +77,9 @@ export default defineNuxtModule<AssistantModuleOptions>({
     )
 
     if (!hasAiGatewayAuth) {
-      log.warn('AI assistant disabled: neither AI_GATEWAY_API_KEY nor VERCEL_OIDC_TOKEN found')
+      nuxt.hook('modules:done', () => {
+        log.warn('AI assistant disabled: neither `AI_GATEWAY_API_KEY` nor `VERCEL_OIDC_TOKEN` found')
+      })
       return
     }
 

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

@@ -1,9 +1,27 @@
 import { streamText, convertToModelMessages, createUIMessageStream, createUIMessageStreamResponse } from 'ai'
 import type { UIMessageStreamWriter, ToolCallPart, ToolSet } from 'ai'
 import { createMCPClient } from '@ai-sdk/mcp'
+import type { H3Event } from 'h3'
 
 const MAX_STEPS = 10
 
+function createLocalFetch(event: H3Event): typeof fetch {
+  const origin = getRequestURL(event).origin
+
+  return (input, init) => {
+    const requestUrl = input instanceof URL
+      ? input
+      : typeof input === 'string'
+        ? new URL(input, origin)
+        : new URL(input.url)
+    const localPath = requestUrl.origin === origin
+      ? `${requestUrl.pathname}${requestUrl.search}`
+      : requestUrl.toString()
+
+    return event.fetch(localPath, init)
+  }
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function stopWhenResponseComplete({ steps }: { steps: any[] }): boolean {
   const lastStep = steps.at(-1)
@@ -66,15 +84,29 @@ export default defineEventHandler(async (event) => {
   const mcpServer = config.assistant.mcpServer
   const isExternalUrl = mcpServer.startsWith('http://') || mcpServer.startsWith('https://')
   const baseURL = config.app?.baseURL?.replace(/\/$/, '') || ''
-  const mcpUrl = isExternalUrl
-    ? mcpServer
-    : import.meta.dev
-      ? `http://localhost:3000${baseURL}${mcpServer}`
-      : `${getRequestURL(event).origin}${baseURL}${mcpServer}`
-
-  const httpClient = await createMCPClient({
-    transport: { type: 'http', url: mcpUrl },
-  })
+
+  let transport: Parameters<typeof createMCPClient>[0]['transport']
+  if (isExternalUrl) {
+    transport = {
+      type: 'http',
+      url: mcpServer,
+    }
+  }
+  else if (import.meta.dev) {
+    transport = {
+      type: 'http',
+      url: `http://localhost:3000${baseURL}${mcpServer}`,
+    }
+  }
+  else {
+    transport = {
+      type: 'http',
+      url: `${getRequestURL(event).origin}${baseURL}${mcpServer}`,
+      fetch: createLocalFetch(event),
+    }
+  }
+
+  const httpClient = await createMCPClient({ transport })
   const mcpTools = await httpClient.tools()
 
   const stream = createUIMessageStream({

package/modules/config.ts

@@ -5,10 +5,11 @@ import { join } from 'node:path'
 import { inferSiteURL, getPackageJsonMetadata } from '../utils/meta'
 import { getGitBranch, getGitEnv, getLocalGitInfo } from '../utils/git'
 
-const log = logger.withTag('Docus')
+const log = logger.withTag('docus')
 
 type I18nLocale = string | { code: string, name?: string }
 type DocusI18nOptions = { locales?: I18nLocale[], strategy?: string }
+type DocusMcpOptions = { route?: string, enabled?: boolean }
 type RegisterModuleOptions = {
   langDir: string
   locales: Array<{ code: string, name: string, file: string }>
@@ -39,7 +40,7 @@ export default defineNuxtModule({
       url,
       name: siteName,
       debug: false,
-    })
+    }) as typeof nuxt.options.site
 
     nuxt.options.appConfig.header = defu(nuxt.options.appConfig.header, {
       title: siteName,
@@ -58,6 +59,16 @@ export default defineNuxtModule({
       branch: getGitBranch(),
     })
 
+    /*
+    ** MCP route (expose to client so the page header dropdown stays in sync
+    ** with the user-configured `mcp.route` from @nuxtjs/mcp-toolkit)
+    */
+    const mcpOptions = (nuxt.options as typeof nuxt.options & { mcp?: DocusMcpOptions }).mcp
+    nuxt.options.runtimeConfig.public.mcp = defu(
+      nuxt.options.runtimeConfig.public.mcp as DocusMcpOptions | undefined,
+      { route: mcpOptions?.route || '/mcp' },
+    )
+
     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

package/modules/css.ts

@@ -1,21 +1,37 @@
-import { defineNuxtModule, addTemplate, createResolver } from '@nuxt/kit'
-import { joinURL } from 'ufo'
+import { defineNuxtModule, addTemplate, createResolver, logger } from '@nuxt/kit'
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'pathe'
 import { resolveModulePath } from 'exsolve'
 
+const log = logger.withTag('docus')
+
 export default defineNuxtModule({
   meta: {
-    name: 'css',
+    name: 'docus-css',
   },
   async setup(_options, nuxt) {
-    const dir = nuxt.options.rootDir
     const resolver = createResolver(import.meta.url)
 
-    const contentDir = joinURL(dir, 'content')
+    const contentDir = resolve(nuxt.options.rootDir, 'content')
     const uiPath = resolveModulePath('@nuxt/ui', { from: import.meta.url, conditions: ['style'] })
     const tailwindPath = resolveModulePath('tailwindcss', { from: import.meta.url, conditions: ['style'] })
     const layerDir = resolver.resolve('../app')
     const assistantDir = resolver.resolve('../modules/assistant')
 
+    let userDocusPath: string | null = resolve(nuxt.options.srcDir, 'app.css')
+    if (existsSync(userDocusPath)) {
+      const userDocusCss = await readFile(userDocusPath, 'utf-8')
+      if (userDocusCss.includes('@import "tailwindcss"')) {
+        nuxt.hook('modules:done', () => {
+          log.warn('`app.css` contains `@import "tailwindcss";` consider removing it to avoid duplicate css.')
+        })
+      }
+    }
+    else {
+      userDocusPath = null
+    }
+
     const cssTemplate = addTemplate({
       filename: 'docus.css',
       getContents: () => {
@@ -25,7 +41,12 @@ export default defineNuxtModule({
 @source "${contentDir.replace(/\\/g, '/')}/**/*";
 @source "${layerDir.replace(/\\/g, '/')}/**/*";
 @source "../../app.config.ts";
-@source "${assistantDir.replace(/\\/g, '/')}/**/*";`
+@source "${assistantDir.replace(/\\/g, '/')}/**/*";
+
+:root {
+  --ui-container: 90rem;
+}
+` + (userDocusPath ? `\n@import ${JSON.stringify(userDocusPath)};` : '')
       },
     })
 

package/modules/markdown-rewrite.ts

@@ -2,7 +2,7 @@ import { defineNuxtModule, logger } from '@nuxt/kit'
 import { resolve } from 'node:path'
 import { readFile, writeFile } from 'node:fs/promises'
 
-const log = logger.withTag('Docus')
+const log = logger.withTag('docus')
 
 type I18nLocale = string | { code: string }
 type DocusI18nOptions = { locales?: I18nLocale[] }
@@ -32,16 +32,22 @@ export default defineNuxtModule({
           return
         }
 
-        // Always redirect / to /llms.txt
+        // Always redirect / to /llms.txt and ensure plain text content type
+        const markdownHeaders = {
+          'content-type': 'text/markdown; charset=utf-8',
+        }
+
         const routes = [
           {
             src: '^/$',
             dest: '/llms.txt',
+            headers: markdownHeaders,
             has: [{ type: 'header', key: 'accept', value: '(.*)text/markdown(.*)' }],
           },
           {
             src: '^/$',
             dest: '/llms.txt',
+            headers: markdownHeaders,
             has: [{ type: 'header', key: 'user-agent', value: 'curl/.*' }],
           },
         ]
@@ -66,11 +72,13 @@ export default defineNuxtModule({
             {
               src: `^/(${localePattern})$`,
               dest: '/llms.txt',
+              headers: markdownHeaders,
               has: [{ type: 'header', key: 'accept', value: '(.*)text/markdown(.*)' }],
             },
             {
               src: `^/(${localePattern})$`,
               dest: '/llms.txt',
+              headers: markdownHeaders,
               has: [{ type: 'header', key: 'user-agent', value: 'curl/.*' }],
             },
           )
@@ -109,11 +117,13 @@ export default defineNuxtModule({
               {
                 src: `^${pagePath}$`,
                 dest: rawPath,
+                headers: markdownHeaders,
                 has: [{ type: 'header', key: 'accept', value: '(.*)text/markdown(.*)' }],
               },
               {
                 src: `^${pagePath}$`,
                 dest: rawPath,
+                headers: markdownHeaders,
                 has: [{ type: 'header', key: 'user-agent', value: 'curl/.*' }],
               },
             ]

package/modules/skills/index.ts

@@ -19,7 +19,7 @@ export interface SkillsModuleOptions {
 const SKILL_NAME_REGEX = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
 const MAX_NAME_LENGTH = 64
 
-const log = logger.withTag('Docus')
+const log = logger.withTag('docus')
 
 const defaults: Required<SkillsModuleOptions> = {
   dir: 'skills',
@@ -38,7 +38,9 @@ export default defineNuxtModule<SkillsModuleOptions>({
     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.hook('modules:done', () => {
+      log.info(`Found ${catalog.length} agent skill${catalog.length > 1 ? 's' : ''}: ${catalog.map(s => s.name).join(', ')}`)
+    })
 
     nuxt.options.runtimeConfig.skills = { catalog }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docus",
   "description": "Nuxt layer for Docus documentation theme",
-  "version": "5.10.0",
+  "version": "5.11.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "repository": {
@@ -23,39 +23,40 @@
     "README.md"
   ],
   "dependencies": {
-    "@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",
+    "@ai-sdk/gateway": "^3.0.104",
+    "@ai-sdk/mcp": "^1.0.36",
+    "@ai-sdk/vue": "3.0.168",
+    "@iconify-json/lucide": "^1.2.102",
+    "@iconify-json/simple-icons": "^1.2.79",
     "@iconify-json/vscode-icons": "^1.2.45",
-    "@nuxt/content": "^3.12.0",
+    "@nuxt/content": "^3.13.0",
     "@nuxt/image": "^2.0.0",
     "@nuxt/kit": "^4.4.2",
-    "@nuxt/ui": "^4.6.0",
+    "@nuxt/ui": "^4.7.1",
     "@nuxtjs/i18n": "^10.2.4",
-    "@nuxtjs/mcp-toolkit": "^0.13.2",
-    "@nuxtjs/mdc": "^0.21.0",
-    "@nuxtjs/robots": "^6.0.6",
+    "@nuxtjs/mcp-toolkit": "^0.13.4",
+    "@nuxtjs/mdc": "^0.21.1",
+    "@nuxtjs/robots": "^6.0.7",
     "@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",
+    "@takumi-rs/core": "^1.0.15",
     "@vueuse/core": "^14.2.1",
-    "ai": "6.0.141",
-    "defu": "^6.1.4",
+    "ai": "6.0.168",
+    "defu": "^6.1.7",
     "exsolve": "^1.0.8",
     "git-url-parse": "^16.1.0",
-    "motion-v": "^2.2.0",
+    "motion-v": "^2.2.1",
     "nuxt-llms": "^0.2.0",
-    "nuxt-og-image": "^6.3.1",
+    "nuxt-og-image": "^6.4.5",
+    "pathe": "^2.0.3",
     "pkg-types": "^2.3.0",
     "scule": "^1.3.0",
     "shiki-stream": "^0.1.4",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.3",
     "ufo": "^1.6.3",
-    "yaml": "^2.7.1",
+    "yaml": "^2.8.3",
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2"
   },

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

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { joinURL } from 'ufo'
 import { queryCollection } from '@nuxt/content/server'
 import type { Collections } from '@nuxt/content'
 import { getAvailableLocales, getCollectionFromPath } from '../../utils/content'
@@ -33,11 +34,13 @@ WORKFLOW: This tool returns the complete page content including title, descripti
   cache: '1h',
   handler: async ({ path }) => {
     const event = useEvent()
-    const config = useRuntimeConfig(event).public
+    const config = useRuntimeConfig(event)
+    const publicConfig = config.public
     const siteUrl = getRequestURL(event).origin || inferSiteURL()
+    const baseURL = config.app?.baseURL || '/'
 
-    const availableLocales = getAvailableLocales(config)
-    const collectionName = config.i18n?.locales
+    const availableLocales = getAvailableLocales(publicConfig)
+    const collectionName = publicConfig.i18n?.locales
       ? getCollectionFromPath(path, availableLocales)
       : 'docs'
 
@@ -58,7 +61,7 @@ WORKFLOW: This tool returns the complete page content including title, descripti
         path: page.path,
         description: page.description,
         content,
-        url: `${siteUrl}${page.path}`,
+        url: siteUrl ? joinURL(siteUrl, baseURL, page.path) : joinURL(baseURL, page.path),
       }
     }
     catch (error) {

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

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { joinURL } from 'ufo'
 import { queryCollection } from '@nuxt/content/server'
 import type { Collections } from '@nuxt/content'
 import { getCollectionsToQuery, getAvailableLocales } from '../../utils/content'
@@ -39,10 +40,12 @@ OUTPUT: Returns a structured list with:
   cache: '1h',
   handler: async ({ locale }) => {
     const event = useEvent()
-    const config = useRuntimeConfig(event).public
+    const config = useRuntimeConfig(event)
+    const publicConfig = config.public
 
     const siteUrl = getRequestURL(event).origin || inferSiteURL()
-    const availableLocales = getAvailableLocales(config)
+    const baseURL = config.app?.baseURL || '/'
+    const availableLocales = getAvailableLocales(publicConfig)
     const collections = getCollectionsToQuery(locale, availableLocales)
 
     try {
@@ -57,7 +60,7 @@ OUTPUT: Returns a structured list with:
             path: page.path,
             description: page.description,
             locale: collectionName.replace('docs_', ''),
-            url: `${siteUrl}${page.path}`,
+            url: siteUrl ? joinURL(siteUrl, baseURL, page.path) : joinURL(baseURL, page.path),
           }))
         }),
       )