docus 5.11.0 → 5.12.1

package/modules/assistant/runtime/composables/useAssistant.ts

@@ -1,7 +1,7 @@
 import type { UIMessage } from 'ai'
-import { useAppConfig, useRuntimeConfig, useState } from '#imports'
-import { useMediaQuery } from '@vueuse/core'
-import { computed } from 'vue'
+import { useAppConfig, useRuntimeConfig } from '#imports'
+import { createSharedComposable, useLocalStorage } from '@vueuse/core'
+import { computed, ref, watch } from 'vue'
 import type { FaqCategory, FaqQuestions, LocalizedFaqQuestions } from '../types'
 
 function normalizeFaqQuestions(questions: FaqQuestions): FaqCategory[] {
@@ -19,10 +19,7 @@ function normalizeFaqQuestions(questions: FaqQuestions): FaqCategory[] {
   return questions as FaqCategory[]
 }
 
-const PANEL_WIDTH_COMPACT = 360
-const PANEL_WIDTH_EXPANDED = 520
-
-export function useAssistant() {
+export const useAssistant = createSharedComposable(() => {
   const config = useRuntimeConfig()
   const appConfig = useAppConfig()
   const assistantRuntimeConfig = config.public.assistant as { enabled?: boolean } | undefined
@@ -30,26 +27,37 @@ export function useAssistant() {
   const docusRuntimeConfig = appConfig.docus as { locale?: string } | undefined
   const isEnabled = computed(() => assistantRuntimeConfig?.enabled ?? false)
 
-  const isOpen = useState('assistant-open', () => false)
-  const isExpanded = useState('assistant-expanded', () => false)
-  const messages = useState<UIMessage[]>('assistant-messages', () => [])
-  const pendingMessage = useState<string | undefined>('assistant-pending', () => undefined)
+  const storageOpen = useLocalStorage('assistant-open', false)
+  const messages = useLocalStorage<UIMessage[]>('assistant-messages', [])
+
+  const isOpen = ref(false)
+  const isStudioExpanded = ref(false)
 
-  const isMobile = useMediaQuery('(max-width: 767px)')
-  const panelWidth = computed(() => isExpanded.value ? PANEL_WIDTH_EXPANDED : PANEL_WIDTH_COMPACT)
-  const shouldPushContent = computed(() => !isMobile.value && isOpen.value)
+  onNuxtReady(() => {
+    nextTick(() => {
+      isOpen.value = storageOpen.value
+    })
+
+    isStudioExpanded.value = document.body.hasAttribute('data-expand-sidebar')
+    const observer = new MutationObserver(() => {
+      isStudioExpanded.value = document.body.hasAttribute('data-expand-sidebar')
+    })
+    observer.observe(document.body, { attributes: true, attributeFilter: ['data-expand-sidebar'] })
+  })
+
+  watch(isOpen, (value) => {
+    storageOpen.value = value
+  })
 
   const faqQuestions = computed<FaqCategory[]>(() => {
     const faqConfig = assistantConfig?.faqQuestions
     if (!faqConfig) return []
 
-    // Check if it's a localized object (has locale keys like 'en', 'fr')
     if (!Array.isArray(faqConfig)) {
       const localizedConfig = faqConfig as LocalizedFaqQuestions
       const currentLocale = docusRuntimeConfig?.locale || 'en'
       const defaultLocale = config.public.i18n?.defaultLocale || 'en'
 
-      // Try current locale, then default locale, then first available
       const questions = localizedConfig[currentLocale]
         || localizedConfig[defaultLocale]
         || Object.values(localizedConfig)[0]
@@ -61,51 +69,39 @@ export function useAssistant() {
   })
 
   function open(initialMessage?: string, clearPrevious = false) {
+    if (isStudioExpanded.value) return
+
     if (clearPrevious) {
       messages.value = []
     }
 
     if (initialMessage) {
-      pendingMessage.value = initialMessage
+      messages.value = [...messages.value, {
+        id: String(Date.now()),
+        role: 'user' as const,
+        parts: [{ type: 'text' as const, text: initialMessage }],
+      }]
     }
     isOpen.value = true
   }
 
-  function clearPending() {
-    pendingMessage.value = undefined
-  }
-
   function close() {
     isOpen.value = false
   }
 
   function toggle() {
+    if (isStudioExpanded.value) return
     isOpen.value = !isOpen.value
   }
 
-  function clearMessages() {
-    messages.value = []
-  }
-
-  function toggleExpanded() {
-    isExpanded.value = !isExpanded.value
-  }
-
   return {
     isEnabled,
     isOpen,
-    isExpanded,
-    isMobile,
-    panelWidth,
-    shouldPushContent,
+    isStudioExpanded,
     messages,
-    pendingMessage,
     faqQuestions,
     open,
-    clearPending,
     close,
     toggle,
-    toggleExpanded,
-    clearMessages,
   }
-}
+})

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

@@ -1,5 +1,5 @@
-import { streamText, convertToModelMessages, createUIMessageStream, createUIMessageStreamResponse } from 'ai'
-import type { UIMessageStreamWriter, ToolCallPart, ToolSet } from 'ai'
+import { streamText, convertToModelMessages } from 'ai'
+import type { ToolSet } from 'ai'
 import { createMCPClient } from '@ai-sdk/mcp'
 import type { H3Event } from 'h3'
 
@@ -23,11 +23,10 @@ function createLocalFetch(event: H3Event): typeof fetch {
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function stopWhenResponseComplete({ steps }: { steps: any[] }): boolean {
+function stopWhenResponseComplete({ steps }: { steps: { text?: string, toolCalls?: unknown[] }[] }): boolean {
   const lastStep = steps.at(-1)
   if (!lastStep) return false
 
-  // Primary condition: stop when model gives a text response without tool calls
   const hasText = Boolean(lastStep.text && lastStep.text.trim().length > 0)
   const hasNoToolCalls = !lastStep.toolCalls || lastStep.toolCalls.length === 0
 
@@ -57,7 +56,7 @@ function getSystemPrompt(siteName: string) {
 
 **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
+- 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):**
@@ -85,6 +84,9 @@ export default defineEventHandler(async (event) => {
   const isExternalUrl = mcpServer.startsWith('http://') || mcpServer.startsWith('https://')
   const baseURL = config.app?.baseURL?.replace(/\/$/, '') || ''
 
+  const abortController = new AbortController()
+  event.node.req.on('close', () => abortController.abort())
+
   let transport: Parameters<typeof createMCPClient>[0]['transport']
   if (isExternalUrl) {
     transport = {
@@ -109,41 +111,19 @@ export default defineEventHandler(async (event) => {
   const httpClient = await createMCPClient({ transport })
   const mcpTools = await httpClient.tools()
 
-  const stream = createUIMessageStream({
-    execute: async ({ writer }: { writer: UIMessageStreamWriter }) => {
-      const modelMessages = await convertToModelMessages(messages)
-      const result = streamText({
-        model: config.assistant.model,
-        maxOutputTokens: 4000,
-        maxRetries: 2,
-        stopWhen: stopWhenResponseComplete,
-        system: getSystemPrompt(siteName),
-        messages: modelMessages,
-        tools: mcpTools as ToolSet,
-        onStepFinish: ({ toolCalls }: { toolCalls: ToolCallPart[] }) => {
-          if (toolCalls.length === 0) return
-          writer.write({
-            id: toolCalls[0]?.toolCallId,
-            type: 'data-tool-calls',
-            data: {
-              tools: toolCalls.map((tc: ToolCallPart) => {
-                const args = 'args' in tc ? tc.args : 'input' in tc ? tc.input : {}
-                return {
-                  toolName: tc.toolName,
-                  toolCallId: tc.toolCallId,
-                  args,
-                }
-              }),
-            },
-          })
-        },
-      })
-      writer.merge(result.toUIMessageStream())
-    },
-    onFinish: async () => {
-      await httpClient.close()
-    },
-  })
-
-  return createUIMessageStreamResponse({ stream })
+  const closeMcp = () => event.waitUntil(httpClient.close())
+
+  return streamText({
+    model: config.assistant.model,
+    maxOutputTokens: 4000,
+    maxRetries: 2,
+    abortSignal: abortController.signal,
+    stopWhen: stopWhenResponseComplete,
+    system: getSystemPrompt(siteName),
+    messages: await convertToModelMessages(messages),
+    tools: mcpTools as ToolSet,
+    onFinish: closeMcp,
+    onAbort: closeMcp,
+    onError: closeMcp,
+  }).toUIMessageStreamResponse()
 })

package/modules/css.ts

@@ -43,6 +43,14 @@ export default defineNuxtModule({
 @source "../../app.config.ts";
 @source "${assistantDir.replace(/\\/g, '/')}/**/*";
 
+html.dark .shiki span {
+  color: var(--shiki-dark) !important;
+  background-color: var(--shiki-dark-bg) !important;
+  font-style: var(--shiki-dark-font-style) !important;
+  font-weight: var(--shiki-dark-font-weight) !important;
+  text-decoration: var(--shiki-dark-text-decoration) !important;
+}
+
 :root {
   --ui-container: 90rem;
 }

package/nuxt.schema.ts

@@ -297,6 +297,34 @@ export default defineNuxtSchema({
           default: '',
           required: ['', 'light', 'dark'],
         }),
+        shortcuts: group({
+          title: 'Shortcuts',
+          description: 'Keyboard shortcuts configuration.',
+          icon: 'i-lucide-keyboard',
+          fields: {
+            toggleColorMode: field({
+              type: 'string',
+              title: 'Toggle Color Mode',
+              description: 'Shortcut to toggle light and dark mode (e.g., d, meta_d). Leave empty to disable.',
+              icon: 'i-lucide-keyboard',
+              default: 'd',
+            }),
+          },
+        }),
+      },
+    }),
+    search: group({
+      title: 'Search',
+      description: 'Search configuration.',
+      icon: 'i-lucide-search',
+      fields: {
+        fts: field({
+          type: 'boolean',
+          title: 'Full-Text Search',
+          description: 'Use SQLite FTS5 full-text search instead of Fuse.js. Requires @nuxt/content v3.14+.',
+          icon: 'i-lucide-database',
+          default: false,
+        }),
       },
     }),
     assistant: group({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docus",
   "description": "Nuxt layer for Docus documentation theme",
-  "version": "5.11.0",
+  "version": "5.12.1",
   "type": "module",
   "main": "./nuxt.config.ts",
   "repository": {
@@ -23,41 +23,42 @@
     "README.md"
   ],
   "dependencies": {
-    "@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.13.0",
+    "@ai-sdk/gateway": "^3.0.120",
+    "@ai-sdk/mcp": "^1.0.43",
+    "@ai-sdk/vue": "^3.0.191",
+    "@comark/vue": "^0.4.0",
+    "@iconify-json/lucide": "^1.2.111",
+    "@iconify-json/simple-icons": "^1.2.85",
+    "@iconify-json/vscode-icons": "^1.2.53",
+    "@nuxt/content": "^3.14.0",
     "@nuxt/image": "^2.0.0",
-    "@nuxt/kit": "^4.4.2",
-    "@nuxt/ui": "^4.7.1",
-    "@nuxtjs/i18n": "^10.2.4",
-    "@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": "^1.0.15",
-    "@vueuse/core": "^14.2.1",
-    "ai": "6.0.168",
+    "@nuxt/kit": "^4.4.7",
+    "@nuxt/ui": "^4.8.1",
+    "@nuxtjs/i18n": "^10.4.0",
+    "@nuxtjs/mcp-toolkit": "^0.17.2",
+    "@nuxtjs/mdc": "^0.22.0",
+    "@nuxtjs/robots": "^6.0.9",
+    "@shikijs/core": "^4.2.0",
+    "@shikijs/engine-javascript": "^4.2.0",
+    "@shikijs/langs": "^4.2.0",
+    "@shikijs/stream": "^4.2.0",
+    "@shikijs/themes": "^4.2.0",
+    "@takumi-rs/core": "^1.6.0",
+    "@vueuse/core": "^14.3.0",
+    "ai": "^6.0.191",
     "defu": "^6.1.7",
     "exsolve": "^1.0.8",
     "git-url-parse": "^16.1.0",
     "motion-v": "^2.2.1",
     "nuxt-llms": "^0.2.0",
-    "nuxt-og-image": "^6.4.5",
+    "nuxt-og-image": "^6.5.1",
     "pathe": "^2.0.3",
-    "pkg-types": "^2.3.0",
+    "pkg-types": "^2.3.1",
     "scule": "^1.3.0",
-    "shiki-stream": "^0.1.4",
-    "tailwindcss": "^4.2.3",
-    "ufo": "^1.6.3",
-    "yaml": "^2.8.3",
-    "zod": "^4.3.6",
+    "tailwindcss": "^4.3.0",
+    "ufo": "^1.6.4",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3",
     "zod-to-json-schema": "^3.25.2"
   },
   "peerDependencies": {

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

@@ -1,9 +1,9 @@
-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'
+import { queryCollection } from '@nuxt/content/server'
+import { joinURL } from 'ufo'
+import { z } from 'zod'
 import { inferSiteURL } from '../../../utils/meta'
+import { getAvailableLocales, getCollectionFromPath, isNavigationPath } from '../../utils/content'
 
 export default defineMcpTool({
   description: `Retrieves the full content and details of a specific documentation page.
@@ -25,7 +25,9 @@ WORKFLOW: This tool returns the complete page content including title, descripti
     openWorldHint: false,
   },
   inputSchema: {
-    path: z.string().describe('The page path from list-pages or provided by the user (e.g., /en/getting-started/installation)'),
+    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' },
@@ -33,6 +35,10 @@ WORKFLOW: This tool returns the complete page content including title, descripti
   ],
   cache: '1h',
   handler: async ({ path }) => {
+    if (isNavigationPath(path)) {
+      throw createError({ statusCode: 404, message: 'Page not found' })
+    }
+
     const event = useEvent()
     const config = useRuntimeConfig(event)
     const publicConfig = config.public

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

@@ -1,9 +1,9 @@
-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'
+import { queryCollection } from '@nuxt/content/server'
+import { joinURL } from 'ufo'
+import { z } from 'zod'
 import { inferSiteURL } from '../../../utils/meta'
+import { getAvailableLocales, getCollectionsToQuery } from '../../utils/content'
 
 export default defineMcpTool({
   description: `Lists all available documentation pages with their categories and basic information.
@@ -52,6 +52,7 @@ OUTPUT: Returns a structured list with:
       const allPages = await Promise.all(
         collections.map(async (collectionName) => {
           const pages = await queryCollection(event, collectionName as keyof Collections)
+            .where('path', 'NOT LIKE', '%.navigation')
             .select('title', 'path', 'description')
             .all()
 

package/server/routes/sitemap.xml.ts

@@ -1,6 +1,6 @@
 import { queryCollection } from '@nuxt/content/server'
-import { getAvailableLocales, getCollectionsToQuery } from '../utils/content'
 import { inferSiteURL } from '../../utils/meta'
+import { getAvailableLocales, getCollectionsToQuery, isNavigationPath } from '../utils/content'
 
 interface SitemapUrl {
   loc: string
@@ -27,17 +27,20 @@ export default defineEventHandler(async (event) => {
 
   for (const collection of collections) {
     try {
-      const pages = await (queryCollection as unknown as (event: unknown, collection: string) => { all: () => Promise<Array<Record<string, unknown> & { path?: string }>> })(event, collection).all()
+      const pages = await (queryCollection as unknown as (
+        event: unknown,
+        collection: string,
+      ) => { all: () => Promise<Array<Record<string, unknown> & { path?: string }>> })(event, collection).all()
 
       for (const page of pages) {
-        const meta = page as Record<string, unknown>
+        const meta = page.meta as Record<string, unknown>
         const pagePath = page.path || '/'
 
         // Skip pages with sitemap: false in frontmatter
         if (meta.sitemap === false) continue
 
         // Skip .navigation files (used for navigation configuration)
-        if (pagePath.endsWith('.navigation') || pagePath.includes('/.navigation')) continue
+        if (isNavigationPath(pagePath)) continue
 
         const urlEntry: SitemapUrl = {
           loc: pagePath,

package/server/utils/content.ts

@@ -25,6 +25,10 @@ export function getCollectionsToQuery(locale: string | undefined, availableLocal
     : ['docs']
 }
 
+export function isNavigationPath(path: string): boolean {
+  return path.endsWith('.navigation') || path.includes('/.navigation/')
+}
+
 export function getCollectionFromPath(path: string, availableLocales: string[]): string {
   const pathSegments = path.split('/').filter(Boolean)
   const firstSegment = pathSegments[0]

package/modules/assistant/runtime/components/AssistantLoading.vue

@@ -1,164 +0,0 @@
-<script setup lang="ts">
-import { motion } from 'motion-v'
-import { useDocusI18n } from '../../../../app/composables/useDocusI18n'
-
-interface ToolCall {
-  toolCallId: string
-  toolName: string
-  args: Record<string, unknown>
-}
-
-const props = defineProps<{
-  text?: string
-  toolCalls?: ToolCall[]
-  isLoading?: boolean
-}>()
-
-const { t } = useDocusI18n()
-
-const messages = computed(() => [
-  t('assistant.loading.searching'),
-  t('assistant.loading.reading'),
-  t('assistant.loading.analyzing'),
-  t('assistant.loading.finding'),
-])
-
-const finishedMessage = computed(() => t('assistant.loading.finished'))
-
-const currentIndex = ref(0)
-const targetText = computed(() => {
-  if (!props.isLoading) {
-    return finishedMessage.value
-  }
-  return props.text || messages.value[currentIndex.value]
-})
-const displayedText = ref(targetText.value)
-
-const chars = 'abcdefghijklmnopqrstuvwxyz'
-
-function scrambleText(from: string, to: string) {
-  const maxLength = Math.max(from.length, to.length)
-  let frame = 0
-  const totalFrames = 15
-
-  const animate = () => {
-    frame++
-    let result = ''
-
-    for (let i = 0; i < maxLength; i++) {
-      const progress = frame / totalFrames
-      const charProgress = progress * maxLength
-
-      if (i < charProgress - 2) {
-        result += to[i] || ''
-      }
-      else if (i < charProgress) {
-        result += chars[Math.floor(Math.random() * chars.length)]
-      }
-      else {
-        result += from[i] || ''
-      }
-    }
-
-    displayedText.value = result
-
-    if (frame < totalFrames) {
-      requestAnimationFrame(animate)
-    }
-    else {
-      displayedText.value = to
-    }
-  }
-
-  requestAnimationFrame(animate)
-}
-
-let textInterval: ReturnType<typeof setInterval> | null = null
-
-watch(targetText, (newText, oldText) => {
-  if (newText !== oldText && newText && oldText) {
-    scrambleText(oldText, newText)
-  }
-})
-
-// Stop text rotation when loading finishes
-watch(() => props.isLoading, (isLoading) => {
-  if (!isLoading && textInterval) {
-    clearInterval(textInterval)
-    textInterval = null
-  }
-})
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function getToolLabel(toolName: string, args: any) {
-  const path = args?.path || ''
-
-  if (toolName === 'list-pages') {
-    return t('assistant.toolListPages')
-  }
-
-  if (toolName === 'get-page') {
-    return `${t('assistant.toolReadPage')} ${path || '...'}`
-  }
-
-  return toolName
-}
-
-onMounted(() => {
-  // Text rotation only when loading
-  if (!props.text && props.isLoading) {
-    textInterval = setInterval(() => {
-      currentIndex.value = (currentIndex.value + 1) % messages.value.length
-    }, 3500)
-  }
-})
-
-onUnmounted(() => {
-  if (textInterval) clearInterval(textInterval)
-})
-</script>
-
-<template>
-  <div class="flex flex-col gap-2">
-    <!-- Main loader with matrix and text -->
-    <div class="flex items-center text-xs text-muted overflow-hidden">
-      <motion.div
-        v-if="isLoading"
-        :initial="{ opacity: 1, width: 'auto' }"
-        :exit="{ opacity: 0, width: 0 }"
-        :transition="{ duration: 0.2 }"
-        class="shrink-0 mr-2"
-      >
-        <AssistantMatrix />
-      </motion.div>
-      <motion.span
-        :animate="{ x: 0 }"
-        :transition="{ duration: 0.2 }"
-        class="font-mono tracking-tight"
-      >
-        {{ displayedText }}
-      </motion.span>
-    </div>
-
-    <!-- Tool calls displayed below -->
-    <div
-      v-if="toolCalls?.length"
-      class="flex flex-col gap-1"
-      :class="isLoading ? 'pl-[22px]' : 'pl-0'"
-    >
-      <motion.div
-        v-for="tool in toolCalls"
-        :key="`${tool.toolCallId}-${JSON.stringify(tool.args)}`"
-        :initial="{ opacity: 0, x: -4 }"
-        :animate="{ opacity: 1, x: 0 }"
-        :transition="{ duration: 0.15 }"
-        class="flex items-center gap-1.5"
-      >
-        <span class="size-1 rounded-full bg-current opacity-40" />
-        <span class="text-[11px] text-dimmed truncate max-w-[200px]">
-          {{ getToolLabel(tool.toolName, tool.args) }}
-        </span>
-      </motion.div>
-    </div>
-  </div>
-</template>