docus 5.4.4 → 5.5.0

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

@@ -0,0 +1,46 @@
+<script setup lang="ts">
+import { ShikiCachedRenderer } from 'shiki-stream/vue'
+import { useColorMode } from '#imports'
+import { useHighlighter } from '../composables/useHighlighter'
+
+const colorMode = useColorMode()
+const highlighter = await useHighlighter()
+const props = defineProps<{
+  code: string
+  language: string
+  class?: string
+  meta?: string
+}>()
+const trimmedCode = computed(() => {
+  return props.code.trim().replace(/`+$/, '')
+})
+const lang = computed(() => {
+  switch (props.language) {
+    case 'vue':
+      return 'vue'
+    case 'javascript':
+      return 'js'
+    case 'typescript':
+      return 'ts'
+    case 'css':
+      return 'css'
+    default:
+      return props.language
+  }
+})
+const key = computed(() => {
+  return `${lang.value}-${colorMode.value}`
+})
+</script>
+
+<template>
+  <ProsePre v-bind="props">
+    <ShikiCachedRenderer
+      :key="key"
+      :highlighter="highlighter"
+      :code="trimmedCode"
+      :lang="lang"
+      :theme="colorMode.value === 'dark' ? 'material-theme-palenight' : 'material-theme-lighter'"
+    />
+  </ProsePre>
+</template>

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

@@ -0,0 +1,107 @@
+import type { UIMessage } from 'ai'
+import { useMediaQuery } from '@vueuse/core'
+import type { FaqCategory, FaqQuestions, LocalizedFaqQuestions } from '../types'
+
+function normalizeFaqQuestions(questions: FaqQuestions): FaqCategory[] {
+  if (!questions || (Array.isArray(questions) && questions.length === 0)) {
+    return []
+  }
+
+  if (typeof questions[0] === 'string') {
+    return [{
+      category: 'Questions',
+      items: questions as string[],
+    }]
+  }
+
+  return questions as FaqCategory[]
+}
+
+const PANEL_WIDTH_COMPACT = 360
+const PANEL_WIDTH_EXPANDED = 520
+
+export function useAssistant() {
+  const config = useRuntimeConfig()
+  const appConfig = useAppConfig()
+  const isEnabled = computed(() => config.public.assistant?.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 isMobile = useMediaQuery('(max-width: 767px)')
+  const panelWidth = computed(() => isExpanded.value ? PANEL_WIDTH_EXPANDED : PANEL_WIDTH_COMPACT)
+  const shouldPushContent = computed(() => !isMobile.value && isOpen.value)
+
+  const faqQuestions = computed<FaqCategory[]>(() => {
+    const assistantConfig = appConfig.assistant
+    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 = appConfig.docus?.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]
+
+      return normalizeFaqQuestions(questions || [])
+    }
+
+    return normalizeFaqQuestions(faqConfig)
+  })
+
+  function open(initialMessage?: string, clearPrevious = false) {
+    if (clearPrevious) {
+      messages.value = []
+    }
+
+    if (initialMessage) {
+      pendingMessage.value = initialMessage
+    }
+    isOpen.value = true
+  }
+
+  function clearPending() {
+    pendingMessage.value = undefined
+  }
+
+  function close() {
+    isOpen.value = false
+  }
+
+  function toggle() {
+    isOpen.value = !isOpen.value
+  }
+
+  function clearMessages() {
+    messages.value = []
+  }
+
+  function toggleExpanded() {
+    isExpanded.value = !isExpanded.value
+  }
+
+  return {
+    isEnabled,
+    isOpen,
+    isExpanded,
+    isMobile,
+    panelWidth,
+    shouldPushContent,
+    messages,
+    pendingMessage,
+    faqQuestions,
+    open,
+    clearPending,
+    close,
+    toggle,
+    toggleExpanded,
+    clearMessages,
+  }
+}

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

@@ -0,0 +1,34 @@
+import { createHighlighterCore } from '@shikijs/core'
+import type { HighlighterCore } from '@shikijs/core'
+import { createJavaScriptRegexEngine } from '@shikijs/engine-javascript'
+
+let highlighter: HighlighterCore | null = null
+let promise: Promise<HighlighterCore> | null = null
+
+export const useHighlighter = async () => {
+  if (!promise) {
+    promise = createHighlighterCore({
+      langs: [
+        import('@shikijs/langs/vue'),
+        import('@shikijs/langs/javascript'),
+        import('@shikijs/langs/typescript'),
+        import('@shikijs/langs/css'),
+        import('@shikijs/langs/html'),
+        import('@shikijs/langs/json'),
+        import('@shikijs/langs/yaml'),
+        import('@shikijs/langs/markdown'),
+        import('@shikijs/langs/bash'),
+      ],
+      themes: [
+        import('@shikijs/themes/material-theme-palenight'),
+        import('@shikijs/themes/material-theme-lighter'),
+      ],
+      engine: createJavaScriptRegexEngine(),
+    })
+  }
+  if (!highlighter) {
+    highlighter = await promise
+  }
+
+  return highlighter
+}

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

@@ -0,0 +1,111 @@
+import { streamText, convertToModelMessages, createUIMessageStream, createUIMessageStreamResponse } from 'ai'
+import type { UIMessageStreamWriter, ToolCallPart, ToolSet } from 'ai'
+import { createMCPClient } from '@ai-sdk/mcp'
+
+const MAX_STEPS = 10
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function stopWhenResponseComplete({ steps }: { steps: any[] }): 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
+
+  if (hasText && hasNoToolCalls) return true
+
+  return steps.length >= MAX_STEPS
+}
+
+function getSystemPrompt(siteName: string) {
+  return `You are the documentation assistant for ${siteName}. Help users navigate and understand the project documentation.
+
+**Your identity:**
+- You are an assistant helping users with ${siteName} documentation
+- NEVER use first person ("I", "me", "my") - always refer to the project by name: "${siteName} provides...", "${siteName} supports...", "The project offers..."
+- Be confident and knowledgeable about the project
+- Speak as a helpful guide, not as the documentation itself
+
+**Tool usage (CRITICAL):**
+- You have tools: list-pages (discover pages) and get-page (read a page)
+- If a page title clearly matches the question, read it directly without listing first
+- ALWAYS respond with text after using tools - never end with just tool calls
+
+**Guidelines:**
+- If you can't find something, say "There is no documentation on that yet" or "${siteName} doesn't cover that topic yet"
+- Be concise, helpful, and direct
+- Guide users like a friendly expert would
+
+**FORMATTING RULES (CRITICAL):**
+- NEVER use markdown headings (#, ##, ###, etc.)
+- Use **bold text** for emphasis and section labels
+- Start responses with content directly, never with a heading
+- Use bullet points for lists
+- Keep code examples focused and minimal
+
+**Response style:**
+- Conversational but professional
+- "Here's how you can do that:" instead of "The documentation shows:"
+- "${siteName} supports TypeScript out of the box" instead of "I support TypeScript"
+- Provide actionable guidance, not just information dumps`
+}
+
+export default defineEventHandler(async (event) => {
+  const { messages } = await readBody(event)
+  const config = useRuntimeConfig()
+  const siteConfig = getSiteConfig(event)
+
+  const siteName = siteConfig.name || 'Documentation'
+
+  const mcpServer = config.assistant.mcpServer
+  const isExternalUrl = mcpServer.startsWith('http://') || mcpServer.startsWith('https://')
+  const mcpUrl = isExternalUrl
+    ? mcpServer
+    : import.meta.dev
+      ? `http://localhost:3000${mcpServer}`
+      : `${getRequestURL(event).origin}${mcpServer}`
+
+  const httpClient = await createMCPClient({
+    transport: { type: 'http', url: mcpUrl },
+  })
+  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 })
+})

package/modules/assistant/runtime/types.ts

@@ -0,0 +1,7 @@
+export interface FaqCategory {
+  category: string
+  items: string[]
+}
+
+export type FaqQuestions = string[] | FaqCategory[]
+export type LocalizedFaqQuestions = Record<string, FaqQuestions>

package/modules/config.ts

@@ -1,10 +1,12 @@
-import { createResolver, defineNuxtModule } from '@nuxt/kit'
+import { createResolver, defineNuxtModule, logger } from '@nuxt/kit'
 import { defu } from 'defu'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { inferSiteURL, getPackageJsonMetadata } from '../utils/meta'
 import { getGitBranch, getGitEnv, getLocalGitInfo } from '../utils/git'
 
+const log = logger.withTag('Docus')
+
 export default defineNuxtModule({
   meta: {
     name: 'config',
@@ -68,11 +70,11 @@ export default defineNuxtModule({
         const hasContentFolder = existsSync(contentPath)
 
         if (!hasLocaleFile) {
-          console.warn(`[Docus] Locale file not found: ${localeCode}.json - skipping locale "${localeCode}"`)
+          log.warn(`Locale file not found: ${localeCode}.json - skipping locale "${localeCode}"`)
         }
 
         if (!hasContentFolder) {
-          console.warn(`[Docus] Content folder not found: content/${localeCode}/ - skipping locale "${localeCode}"`)
+          log.warn(`Content folder not found: content/${localeCode}/ - skipping locale "${localeCode}"`)
         }
 
         return hasLocaleFile && hasContentFolder

package/modules/css.ts

@@ -14,6 +14,7 @@ export default defineNuxtModule({
     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')
 
     const cssTemplate = addTemplate({
       filename: 'docus.css',
@@ -23,7 +24,8 @@ export default defineNuxtModule({
 
 @source "${contentDir.replace(/\\/g, '/')}/**/*";
 @source "${layerDir.replace(/\\/g, '/')}/**/*";
-@source "../../app.config.ts";`
+@source "../../app.config.ts";
+@source "${assistantDir.replace(/\\/g, '/')}/**/*";`
       },
     })
 

package/modules/markdown-rewrite.ts

@@ -0,0 +1,130 @@
+import { defineNuxtModule, logger } from '@nuxt/kit'
+import { resolve } from 'node:path'
+import { readFile, writeFile } from 'node:fs/promises'
+
+const log = logger.withTag('Docus')
+
+export default defineNuxtModule({
+  meta: {
+    name: 'markdown-rewrite',
+  },
+  setup(_options, nuxt) {
+    nuxt.hooks.hook('nitro:init', (nitro) => {
+      if (nitro.options.dev || !nitro.options.preset.includes('vercel')) {
+        return
+      }
+
+      nitro.hooks.hook('compiled', async () => {
+        const vcJSON = resolve(nitro.options.output.dir, 'config.json')
+        const vcConfig = JSON.parse(await readFile(vcJSON, 'utf8'))
+
+        // Check if llms.txt exists before setting up any routes
+        let llmsTxt
+        const llmsTxtPath = resolve(nitro.options.output.publicDir, 'llms.txt')
+        try {
+          llmsTxt = await readFile(llmsTxtPath, 'utf-8')
+        }
+        catch {
+          log.warn('llms.txt not found, skipping markdown redirect routes')
+          return
+        }
+
+        // Always redirect / to /llms.txt
+        const routes = [
+          {
+            src: '^/$',
+            dest: '/llms.txt',
+            has: [{ type: 'header', key: 'accept', value: '(.*)text/markdown(.*)' }],
+          },
+          {
+            src: '^/$',
+            dest: '/llms.txt',
+            has: [{ type: 'header', key: 'user-agent', value: 'curl/.*' }],
+          },
+        ]
+
+        // Check if i18n is enabled
+        const isI18nEnabled = !!(nuxt.options.i18n && nuxt.options.i18n.locales)
+        let localeCodes: string[] = []
+
+        if (isI18nEnabled) {
+          // Get locale codes
+          const locales = nuxt.options.i18n.locales || []
+          localeCodes = locales.map((locale) => {
+            return typeof locale === 'string' ? locale : locale.code
+          })
+
+          // Create a regex pattern for all locales (e.g., "en|fr|es")
+          const localePattern = localeCodes.join('|')
+
+          // Add routes for each locale homepage: /{locale} → /llms.txt
+          routes.push(
+            {
+              src: `^/(${localePattern})$`,
+              dest: '/llms.txt',
+              has: [{ type: 'header', key: 'accept', value: '(.*)text/markdown(.*)' }],
+            },
+            {
+              src: `^/(${localePattern})$`,
+              dest: '/llms.txt',
+              has: [{ type: 'header', key: 'user-agent', value: 'curl/.*' }],
+            },
+          )
+        }
+
+        // Parse llms.txt to get all documentation pages
+        const urlRegex = /\[([^\]]+)\]\((https?:\/\/[^)]+)\)/g
+        const matches = [...llmsTxt.matchAll(urlRegex)]
+
+        for (const match of matches) {
+          const url = match[2]
+          if (!url) continue
+
+          try {
+            // Extract path from URL
+            const urlObj = new URL(url)
+            const rawPath = urlObj.pathname
+
+            // Skip root path (already handled)
+            if (rawPath === '/') continue
+
+            // Only process raw markdown URLs from llms.txt
+            if (!rawPath.startsWith('/raw/')) continue
+
+            // Convert /raw/en/getting-started/installation.md to /en/getting-started/installation
+            const pagePath = rawPath.replace('/raw', '').replace(/\.md$/, '')
+
+            // Skip locale homepages (e.g., /en, /fr) - they already redirect to /llms.txt
+            if (isI18nEnabled) {
+              const isLocaleHomepage = localeCodes.some(code => pagePath === `/${code}`)
+              if (isLocaleHomepage) continue
+            }
+
+            // Add redirect routes: page URL → raw markdown URL
+            const docsRoutes = [
+              {
+                src: `^${pagePath}$`,
+                dest: rawPath,
+                has: [{ type: 'header', key: 'accept', value: '(.*)text/markdown(.*)' }],
+              },
+              {
+                src: `^${pagePath}$`,
+                dest: rawPath,
+                has: [{ type: 'header', key: 'user-agent', value: 'curl/.*' }],
+              },
+            ]
+            routes.push(...docsRoutes)
+          }
+          catch {
+            // Skip invalid URLs
+          }
+        }
+
+        vcConfig.routes.unshift(...routes)
+
+        await writeFile(vcJSON, JSON.stringify(vcConfig, null, 2), 'utf8')
+        log.info(`Successfully wrote ${routes.length} routes to ${vcJSON} (serve markdown content to AI agents)`)
+      })
+    })
+  },
+})

package/nuxt.config.ts

@@ -6,6 +6,7 @@ export default defineNuxtConfig({
   modules: [
     resolve('./modules/config'),
     resolve('./modules/routing'),
+    resolve('./modules/markdown-rewrite'),
     resolve('./modules/css'),
     '@nuxt/ui',
     '@nuxt/content',
@@ -19,9 +20,14 @@ export default defineNuxtConfig({
       extendViteConfig((config) => {
         config.optimizeDeps ||= {}
         config.optimizeDeps.include ||= []
-        config.optimizeDeps.include.push('@nuxt/content > slugify')
+        config.optimizeDeps.include.push(
+          '@nuxt/content > slugify',
+          // Fix @vercel/oidc ESM export issue (transitive dep of @ai-sdk/gateway)
+          '@vercel/oidc',
+        )
         config.optimizeDeps.include = config.optimizeDeps.include
           .map(id => id.replace(/^@nuxt\/content > /, 'docus > @nuxt/content > '))
+          .map(id => id.replace(/^@vercel\/oidc$/, 'docus > @vercel/oidc'))
       })
     },
   ],
@@ -44,6 +50,11 @@ export default defineNuxtConfig({
       },
     },
   },
+  mdc: {
+    highlight: {
+      shikiEngine: 'javascript',
+    },
+  },
   experimental: {
     asyncContext: true,
   },
@@ -76,6 +87,7 @@ export default defineNuxtConfig({
       nitroConfig.prerender = nitroConfig.prerender || {}
       nitroConfig.prerender.routes = nitroConfig.prerender.routes || []
       nitroConfig.prerender.routes.push(...(routes || []))
+      nitroConfig.prerender.routes.push('/sitemap.xml')
     },
   },
   icon: {

package/nuxt.schema.ts

@@ -214,5 +214,68 @@ export default defineNuxtSchema({
         }),
       },
     }),
+    assistant: group({
+      title: 'Assistant',
+      description: 'Assistant configuration.',
+      icon: 'i-lucide-sparkles',
+      fields: {
+        floatingInput: field({
+          type: 'boolean',
+          title: 'Floating Input',
+          description: 'Show the floating input at the bottom of documentation pages.',
+          icon: 'i-lucide-message-circle',
+          default: true,
+        }),
+        explainWithAi: field({
+          type: 'boolean',
+          title: 'Explain with AI',
+          description: 'Show the "Explain with AI" button in the documentation sidebar.',
+          icon: 'i-lucide-brain',
+          default: true,
+        }),
+        faqQuestions: field({
+          type: 'array',
+          title: 'FAQ Questions',
+          description: 'List of FAQ questions. Can be an array of strings or an array of categories with questions.',
+          icon: 'i-lucide-help-circle',
+          default: [],
+        }),
+        shortcuts: group({
+          title: 'Shortcuts',
+          description: 'Keyboard shortcuts configuration.',
+          icon: 'i-lucide-keyboard',
+          fields: {
+            focusInput: field({
+              type: 'string',
+              title: 'Focus Input',
+              description: 'Shortcut to focus the floating input (e.g., meta_i, ctrl_k).',
+              icon: 'i-lucide-keyboard',
+              default: 'meta_i',
+            }),
+          },
+        }),
+        icons: group({
+          title: 'Icons',
+          description: 'Icons configuration.',
+          icon: 'i-lucide-settings',
+          fields: {
+            trigger: field({
+              type: 'icon',
+              title: 'Trigger',
+              description: 'Icon for the AI chat trigger button and slideover header.',
+              icon: 'i-lucide-sparkles',
+              default: 'i-lucide-sparkles',
+            }),
+            explain: field({
+              type: 'icon',
+              title: 'Explain',
+              description: 'Icon for the "Explain with AI" button.',
+              icon: 'i-lucide-brain',
+              default: 'i-lucide-brain',
+            }),
+          },
+        }),
+      },
+    }),
   },
 })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docus",
   "description": "Nuxt layer for Docus documentation theme",
-  "version": "5.4.4",
+  "version": "5.5.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "repository": {
@@ -22,30 +22,39 @@
     "README.md"
   ],
   "dependencies": {
-    "@iconify-json/lucide": "^1.2.86",
-    "@iconify-json/simple-icons": "^1.2.67",
+    "@ai-sdk/gateway": "^3.0.32",
+    "@ai-sdk/mcp": "^1.0.18",
+    "@ai-sdk/vue": "3.0.69",
+    "@iconify-json/lucide": "^1.2.88",
+    "@iconify-json/simple-icons": "^1.2.69",
     "@iconify-json/vscode-icons": "^1.2.40",
     "@nuxt/content": "^3.11.0",
     "@nuxt/image": "^2.0.0",
-    "@nuxt/kit": "^4.2.2",
-    "@nuxt/ui": "^4.3.0",
+    "@nuxt/kit": "^4.3.0",
+    "@nuxt/ui": "^4.4.0",
     "@nuxtjs/i18n": "^10.2.1",
     "@nuxtjs/mcp-toolkit": "^0.6.2",
     "@nuxtjs/mdc": "^0.20.0",
-    "@nuxtjs/robots": "^5.6.7",
-    "@vueuse/core": "^14.1.0",
+    "@nuxtjs/robots": "^5.7.0",
+    "@vueuse/core": "^14.2.0",
+    "ai": "6.0.69",
     "defu": "^6.1.4",
     "exsolve": "^1.0.8",
     "git-url-parse": "^16.1.0",
     "minimark": "^0.2.0",
-    "motion-v": "^1.9.0",
+    "motion-v": "^1.10.2",
     "nuxt-llms": "^0.2.0",
     "nuxt-og-image": "^5.1.13",
     "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.1.18",
     "ufo": "^1.6.3",
-    "zod": "^4.3.5",
+    "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.1"
   },
   "peerDependencies": {