docus 5.4.2 → 5.5.0

package/app/app.vue

@@ -5,6 +5,7 @@ import * as nuxtUiLocales from '@nuxt/ui/locale'
 const { seo } = useAppConfig()
 const site = useSiteConfig()
 const { locale, locales, isEnabled, switchLocalePath } = useDocusI18n()
+const { isEnabled: isAssistantEnabled, panelWidth: assistantPanelWidth, shouldPushContent } = useAssistant()
 
 const nuxtUiLocale = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales] || nuxtUiLocales.en)
 const lang = computed(() => nuxtUiLocale.value.code)
@@ -47,7 +48,7 @@ const { data: navigation } = await useAsyncData(() => `navigation_${collectionNa
   transform: (data: ContentNavigationItem[]) => {
     const rootResult = data.find(item => item.path === '/docs')?.children || data || []
 
-    return rootResult.find(item => item.path === `/${locale.value}`)?.children || rootResult
+    return rootResult.find((item: ContentNavigationItem) => item.path === `/${locale.value}`)?.children || rootResult
   },
   watch: [locale],
 })
@@ -63,17 +64,26 @@ provide('navigation', navigation)
   <UApp :locale="nuxtUiLocale">
     <NuxtLoadingIndicator color="var(--ui-primary)" />
 
-    <AppHeader v-if="$route.meta.header !== false" />
-    <NuxtLayout>
-      <NuxtPage />
-    </NuxtLayout>
-    <AppFooter v-if="$route.meta.footer !== false" />
+    <div
+      class="transition-[margin-right] duration-200 ease-linear will-change-[margin-right]"
+      :style="{ marginRight: shouldPushContent ? `${assistantPanelWidth}px` : '0' }"
+    >
+      <AppHeader v-if="$route.meta.header !== false" />
+      <NuxtLayout>
+        <NuxtPage />
+      </NuxtLayout>
+      <AppFooter v-if="$route.meta.footer !== false" />
+    </div>
 
     <ClientOnly>
       <LazyUContentSearch
         :files="files"
         :navigation="navigation"
       />
+      <template v-if="isAssistantEnabled">
+        <LazyAssistantFloatingInput />
+        <LazyAssistantPanel />
+      </template>
     </ClientOnly>
   </UApp>
 </template>

package/app/components/app/AppHeader.vue

@@ -4,6 +4,7 @@ import { useDocusI18n } from '../../composables/useDocusI18n'
 const appConfig = useAppConfig()
 const site = useSiteConfig()
 
+const { isEnabled: isAssistantEnabled } = useAssistant()
 const { localePath, isEnabled, locales } = useDocusI18n()
 
 const links = computed(() => appConfig.github && appConfig.github.url
@@ -33,6 +34,10 @@ const links = computed(() => appConfig.github && appConfig.github.url
     <template #right>
       <AppHeaderCTA />
 
+      <template v-if="isAssistantEnabled">
+        <AssistantChat />
+      </template>
+
       <template v-if="isEnabled && locales.length > 1">
         <ClientOnly>
           <LanguageSelect />

package/app/components/docs/DocsAsideRightBottom.vue

@@ -1,18 +1,45 @@
 <script setup lang="ts">
+const route = useRoute()
+
+const pageUrl = route.path
 const appConfig = useAppConfig()
 const { t } = useDocusI18n()
+const { isEnabled, open } = useAssistant()
+
+const showExplainWithAi = computed(() => {
+  return isEnabled.value && appConfig.assistant?.explainWithAi !== false
+})
+
+const explainIcon = computed(() => appConfig.assistant?.icons?.explain || 'i-lucide-brain')
 </script>
 
 <template>
   <div
-    v-if="appConfig.toc?.bottom?.links?.length"
+    v-if="appConfig.toc?.bottom?.links?.length || showExplainWithAi"
     class="hidden lg:block space-y-6"
   >
     <USeparator type="dashed" />
 
     <UPageLinks
+      v-if="appConfig.toc?.bottom?.links?.length"
       :title="appConfig.toc?.bottom?.title || t('docs.links')"
       :links="appConfig.toc?.bottom?.links"
     />
+
+    <USeparator
+      v-if="appConfig.toc?.bottom?.links?.length && showExplainWithAi"
+      type="dashed"
+    />
+
+    <UButton
+      v-if="showExplainWithAi"
+      :icon="explainIcon"
+      :label="t('assistant.explainWithAi')"
+      size="sm"
+      variant="link"
+      class="p-0 text-sm"
+      color="neutral"
+      @click="open(`Explain the page ${pageUrl}`, true)"
+    />
   </div>
 </template>

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

@@ -2,7 +2,6 @@
 import { kebabCase } from 'scule'
 import type { ContentNavigationItem, Collections, DocsCollectionItem } from '@nuxt/content'
 import { findPageHeadline } from '@nuxt/content/utils'
-import { addPrerenderPath } from '../../utils/prerender'
 
 definePageMeta({
   layout: 'docs',
@@ -12,6 +11,7 @@ const route = useRoute()
 const { locale, isEnabled, t } = useDocusI18n()
 const appConfig = useAppConfig()
 const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')
+const { shouldPushContent: shouldHideToc } = useAssistant()
 
 const collectionName = computed(() => isEnabled.value ? `docs_${locale.value}` : 'docs')
 
@@ -28,9 +28,6 @@ if (!page.value) {
   throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
 }
 
-// Add the page path to the prerender list
-addPrerenderPath(`/raw${route.path}.md`)
-
 const title = page.value.seo?.title || page.value.title
 const description = page.value.seo?.description || page.value.description
 
@@ -66,10 +63,16 @@ const editLink = computed(() => {
     `${page.value?.stem}.${page.value?.extension}`,
   ].filter(Boolean).join('/')
 })
+
+// Add the page path to the prerender list
+addPrerenderPath(`/raw${route.path}.md`)
 </script>
 
 <template>
-  <UPage v-if="page">
+  <UPage
+    v-if="page"
+    :key="`page-${shouldHideToc}`"
+  >
     <UPageHeader
       :title="page.title"
       :description="page.description"
@@ -128,7 +131,7 @@ const editLink = computed(() => {
     </UPageBody>
 
     <template
-      v-if="page?.body?.toc?.links?.length"
+      v-if="page?.body?.toc?.links?.length && !shouldHideToc"
       #right
     >
       <UContentToc

package/app/plugins/i18n.ts

@@ -1,5 +1,10 @@
-import en from '../../i18n/locales/en.json'
 import type { RouteLocationNormalized } from 'vue-router'
+import { consola } from 'consola'
+
+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')
 
 export default defineNuxtPlugin(async () => {
   const nuxtApp = useNuxtApp()
@@ -8,19 +13,31 @@ export default defineNuxtPlugin(async () => {
 
   // If i18n is not enabled, fetch and provide the configured locale in app config
   if (!i18nConfig) {
-    let locale = 'en'
-    let resolvedMessages: Record<string, unknown> = en
-
     const appConfig = useAppConfig()
-    const configuredLocale = appConfig.docus.locale
-    if (configuredLocale !== 'en') {
-      const localeMessages = await import(`../../i18n/locales/${configuredLocale}.json`)
-      if (!localeMessages) {
-        console.warn(`[Docus] Missing locale file for "${configuredLocale}". Falling back to "en".`)
+    const configuredLocale = appConfig.docus.locale || 'en'
+
+    let locale = configuredLocale
+    let resolvedMessages: Record<string, unknown>
+
+    // Try to load the requested locale file
+    const localeKey = `../../i18n/locales/${configuredLocale}.json`
+    const localeLoader = localeFiles[localeKey]
+
+    if (localeLoader) {
+      const localeModule = await localeLoader()
+      resolvedMessages = localeModule.default
+    }
+    else {
+      log.warn(`Missing locale file for "${configuredLocale}". Falling back to "en".`)
+      locale = 'en'
+      const fallbackKey = '../../i18n/locales/en.json'
+      const fallbackLoader = localeFiles[fallbackKey]
+      if (fallbackLoader) {
+        const fallbackModule = await fallbackLoader()
+        resolvedMessages = fallbackModule.default
       }
       else {
-        locale = configuredLocale
-        resolvedMessages = localeMessages
+        resolvedMessages = {} as Record<string, unknown>
       }
     }
 

package/app/types/index.d.ts

@@ -1,3 +1,7 @@
+import type { FaqQuestions, LocalizedFaqQuestions } from '../../modules/assistant/runtime/types'
+
+export type { FaqCategory, FaqQuestions, LocalizedFaqQuestions } from '../../modules/assistant/runtime/types'
+
 declare module 'nuxt/schema' {
   interface AppConfig {
     docus: {
@@ -36,6 +40,51 @@ declare module 'nuxt/schema' {
       branch: string
       rootDir?: string
     } | false
+    assistant?: {
+      /**
+       * Show the floating input at the bottom of documentation pages.
+       * @default true
+       */
+      floatingInput?: boolean
+      /**
+       * Show the "Explain with AI" button in the documentation sidebar.
+       * @default true
+       */
+      explainWithAi?: boolean
+      /**
+       * FAQ questions to display in the chat slideover.
+       * Can be a simple array of strings, an array of categories, or a locale-based object.
+       * @example Simple format: ['How to install?', 'How to configure?']
+       * @example Category format: [{ category: 'Getting Started', items: ['How to install?'] }]
+       * @example Localized format: { en: ['How to install?'], fr: ['Comment installer ?'] }
+       */
+      faqQuestions?: FaqQuestions | LocalizedFaqQuestions
+      /**
+       * Keyboard shortcuts configuration.
+       */
+      shortcuts?: {
+        /**
+         * Shortcut to focus the floating input.
+         * @default 'meta_i'
+         */
+        focusInput?: string
+      }
+      /**
+       * Icons configuration.
+       */
+      icons?: {
+        /**
+         * Icon for the assistant trigger button and slideover header.
+         * @default 'i-lucide-sparkles'
+         */
+        trigger?: string
+        /**
+         * Icon for the "Explain with AI" button.
+         * @default 'i-lucide-brain'
+         */
+        explain?: string
+      }
+    }
   }
 }
 

package/content.config.ts

@@ -21,7 +21,7 @@ let collections: Record<string, DefinedCollection>
 if (locales && Array.isArray(locales)) {
   collections = {}
   for (const locale of locales) {
-    const code = typeof locale === 'string' ? locale : locale.code
+    const code = (typeof locale === 'string' ? locale : locale.code).replace('-', '_')
 
     collections[`landing_${code}`] = defineCollection({
       type: 'page',

package/i18n/locales/en.json

@@ -18,5 +18,32 @@
     "toc": "On this page",
     "report": "Report an issue",
     "edit": "Edit this page"
+  },
+  "assistant": {
+    "title": "Ask AI",
+    "placeholder": "Ask a question...",
+    "tooltip": "Ask AI a question",
+    "tryAsking": "Try asking a question",
+    "askAnything": "Ask anything...",
+    "clearChat": "Clear chat",
+    "close": "Close",
+    "expand": "Expand",
+    "collapse": "Collapse",
+    "thinking": "Thinking...",
+    "askMeAnything": "Ask anything",
+    "askMeAnythingDescription": "Get help navigating the documentation, understanding concepts, and finding answers.",
+    "faq": "FAQ",
+    "chatCleared": "Chat is cleared on refresh",
+    "lineBreak": "Line break",
+    "explainWithAi": "Explain with AI",
+    "toolListPages": "Listed documentation pages",
+    "toolReadPage": "Read",
+    "loading": {
+      "searching": "Searching the documentation",
+      "reading": "Reading through the docs",
+      "analyzing": "Analyzing the content",
+      "finding": "Finding the best answer",
+      "finished": "Sources used"
+    }
   }
 }

package/i18n/locales/fr.json

@@ -18,5 +18,32 @@
     "toc": "Sur cette page",
     "report": "Signaler un problème",
     "edit": "Éditer cette page"
+  },
+  "assistant": {
+    "title": "Demander à l'IA",
+    "placeholder": "Posez une question...",
+    "tooltip": "Poser une question à l'IA",
+    "tryAsking": "Essayez de poser une question",
+    "askAnything": "Demandez n'importe quoi...",
+    "clearChat": "Effacer le chat",
+    "close": "Fermer",
+    "expand": "Agrandir",
+    "collapse": "Réduire",
+    "thinking": "Réflexion...",
+    "askMeAnything": "Posez une question",
+    "askMeAnythingDescription": "Obtenez de l'aide pour naviguer dans la documentation, comprendre des concepts et trouver des réponses.",
+    "faq": "FAQ",
+    "chatCleared": "Le chat est effacé au rechargement",
+    "lineBreak": "Retour à la ligne",
+    "explainWithAi": "Expliquer avec l'IA",
+    "toolListPages": "Pages de documentation listées",
+    "toolReadPage": "Lecture de",
+    "loading": {
+      "searching": "Recherche dans la documentation",
+      "reading": "Lecture des documents",
+      "analyzing": "Analyse du contenu",
+      "finding": "Recherche de la meilleure réponse",
+      "finished": "Sources utilisées"
+    }
   }
-} 
+}

package/modules/assistant/README.md

@@ -0,0 +1,213 @@
+# Assistant Module
+
+A Nuxt module that provides an AI-powered chat interface using MCP (Model Context Protocol) tools.
+
+## Features
+
+- AI chat slideover component with streaming responses
+- Floating input component for quick questions
+- MCP tools integration for documentation search
+- Syntax highlighting for code blocks
+- FAQ suggestions
+- Persistent chat state
+- Keyboard shortcuts support
+
+## Installation
+
+1. Copy the `modules/assistant` folder to your Nuxt project
+2. Install the required dependencies:
+
+```bash
+pnpm add @ai-sdk/mcp @ai-sdk/vue @ai-sdk/gateway ai motion-v shiki shiki-stream
+```
+
+3. Add the module to your `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['./modules/assistant'],
+
+  assistant: {
+    apiPath: '/__docus__/assistant',
+    mcpServer: '/mcp',
+    model: 'google/gemini-3-flash',
+  }
+})
+```
+
+4. Set up your API key as an environment variable:
+
+```bash
+AI_GATEWAY_API_KEY=your-gateway-key
+```
+
+> **Note:** The module will only be enabled if `AI_GATEWAY_API_KEY` is detected. If no key is found, the module is disabled and a message is logged to the console.
+
+## Usage
+
+Add the components to your app:
+
+```vue
+<template>
+  <div>
+    <!-- Button to open the chat -->
+    <AssistantChat />
+
+    <!-- Chat panel (place once in your app/layout) -->
+    <AssistantPanel />
+  </div>
+</template>
+```
+
+### FAQ Questions
+
+Configure FAQ questions in your `app.config.ts`:
+
+```ts
+export default defineAppConfig({
+  assistant: {
+    faqQuestions: [
+      {
+        category: 'Getting Started',
+        items: ['How do I install?', 'How do I configure?'],
+      },
+      {
+        category: 'Advanced',
+        items: ['How do I customize?'],
+      },
+    ],
+  },
+})
+```
+
+You can also use localized FAQ questions:
+
+```ts
+export default defineAppConfig({
+  assistant: {
+    faqQuestions: {
+      en: ['How do I install?', 'How do I configure?'],
+      fr: ['Comment installer ?', 'Comment configurer ?'],
+    },
+  },
+})
+```
+
+### Floating Input
+
+Use `AssistantFloatingInput` for a floating input at the bottom of the page.
+
+**Recommended:** Use `Teleport` to render the floating input at the body level, ensuring it stays fixed at the bottom regardless of your component hierarchy:
+
+```vue
+<template>
+  <div>
+    <!-- Teleport to body for proper fixed positioning -->
+    <Teleport to="body">
+      <ClientOnly>
+        <LazyAssistantFloatingInput />
+      </ClientOnly>
+    </Teleport>
+
+    <!-- Chat panel (required to display responses) -->
+    <AssistantPanel />
+  </div>
+</template>
+```
+
+The floating input:
+- Appears at the bottom center of the viewport
+- Automatically hides when the chat slideover is open
+- Expands on focus for better typing experience
+- Supports keyboard shortcuts: `⌘I` to focus, `Escape` to blur
+
+### Programmatic Control
+
+Use the `useAssistant` composable to control the chat:
+
+```vue
+<script setup>
+const { open, close, toggle, isOpen, messages, clearMessages } = useAssistant()
+
+// Open chat with an initial message
+open('How do I install the module?')
+
+// Open and clear previous messages
+open('New question', true)
+
+// Toggle chat visibility
+toggle()
+
+// Clear all messages
+clearMessages()
+</script>
+```
+
+## Module Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiPath` | `string` | `/__docus__/assistant` | API endpoint path for the chat |
+| `mcpServer` | `string` | `/mcp` | MCP server path or full URL (e.g., `https://docs.example.com/mcp` for external servers) |
+| `model` | `string` | `google/gemini-3-flash` | AI model identifier for AI SDK Gateway |
+
+## Components
+
+### `<AssistantChat>`
+
+Button to toggle the chat panel. The tooltip text is automatically translated using i18n (`assistant.tooltip`).
+
+### `<AssistantPanel>`
+
+Main chat interface displayed as a side panel. Configuration is done via `app.config.ts` (see FAQ Questions section above).
+
+### `<AssistantFloatingInput>`
+
+Floating input field positioned at the bottom of the viewport. No props required.
+
+**Keyboard shortcuts:**
+- `⌘I` / `Ctrl+I` - Focus the input
+- `Escape` - Blur the input
+- `Enter` - Submit the question
+
+## Composables
+
+### `useAssistant`
+
+Main composable for controlling the chat state.
+
+```ts
+const {
+  isOpen,         // Ref<boolean> - Whether the chat is open
+  messages,       // Ref<UIMessage[]> - Chat messages
+  pendingMessage, // Ref<string | undefined> - Pending message to send
+  faqQuestions,   // ComputedRef<FaqCategory[]> - FAQ questions from config
+  open,           // (message?: string, clearPrevious?: boolean) => void
+  close,          // () => void
+  toggle,         // () => void
+  clearMessages,  // () => void
+  clearPending,   // () => void
+} = useAssistant()
+```
+
+### `useHighlighter`
+
+Composable for syntax highlighting code blocks with Shiki.
+
+## Requirements
+
+- Nuxt 4.x
+- Nuxt UI 3.x (for `USlideover`, `UButton`, `UTextarea`, `UChatMessages`, etc.)
+- An MCP server running (path configurable via `mcpServer`)
+- `AI_GATEWAY_API_KEY` environment variable
+
+## Customization
+
+### System Prompt
+
+To customize the AI's behavior, edit the system prompt in:
+`runtime/server/api/search.ts`
+
+### Styling
+
+The components use Nuxt UI and Tailwind CSS design tokens. Customize the appearance by modifying the component files or overriding the UI props.

package/modules/assistant/index.ts

@@ -0,0 +1,100 @@
+import { addComponent, addImports, addServerHandler, createResolver, defineNuxtModule, logger } from '@nuxt/kit'
+
+export interface AssistantModuleOptions {
+  /**
+   * API endpoint path for the assistant
+   * @default '/__docus__/assistant'
+   */
+  apiPath?: string
+  /**
+   * MCP server URL or path.
+   * - Use a path like '/mcp' to use the built-in Docus MCP server
+   * - Use a full URL like 'https://docs.example.com/mcp' for external MCP servers
+   * @default '/mcp'
+   */
+  mcpServer?: string
+  /**
+   * AI model to use via AI SDK Gateway
+   * @default 'google/gemini-3-flash'
+   */
+  model?: string
+}
+
+const log = logger.withTag('Docus')
+
+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
+
+    const { resolve } = createResolver(import.meta.url)
+
+    nuxt.options.runtimeConfig.public.assistant = {
+      enabled: hasApiKey,
+      apiPath: options.apiPath!,
+    }
+
+    addImports([
+      {
+        name: 'useAssistant',
+        from: resolve('./runtime/composables/useAssistant'),
+      },
+    ])
+
+    const components = [
+      'AssistantChat',
+      'AssistantPanel',
+      'AssistantFloatingInput',
+      'AssistantLoading',
+      'AssistantMatrix',
+    ]
+
+    components.forEach(name =>
+      addComponent({
+        name,
+        filePath: hasApiKey
+          ? resolve(`./runtime/components/${name}.vue`)
+          : resolve('./runtime/components/AssistantChatDisabled.vue'),
+      }),
+    )
+
+    if (!hasApiKey) {
+      log.warn('[Docus] AI assistant disabled: AI_GATEWAY_API_KEY not found')
+      return
+    }
+
+    nuxt.options.runtimeConfig.assistant = {
+      mcpServer: options.mcpServer!,
+      model: options.model!,
+    }
+
+    const routePath = options.apiPath!.replace(/^\//, '')
+    addServerHandler({
+      route: `/${routePath}`,
+      handler: resolve('./runtime/server/api/search'),
+    })
+  },
+})
+
+declare module 'nuxt/schema' {
+  interface PublicRuntimeConfig {
+    assistant: {
+      enabled: boolean
+      apiPath: string
+    }
+  }
+  interface RuntimeConfig {
+    assistant: {
+      mcpServer: string
+      model: string
+    }
+  }
+}

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

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import { useDocusI18n } from '../../../../app/composables/useDocusI18n'
+
+const appConfig = useAppConfig()
+const { toggle } = useAssistant()
+const { t } = useDocusI18n()
+
+const tooltipText = computed(() => t('assistant.tooltip'))
+const triggerIcon = computed(() => appConfig.assistant?.icons?.trigger || 'i-lucide-sparkles')
+</script>
+
+<template>
+  <UTooltip :text="tooltipText">
+    <UButton
+      :icon="triggerIcon"
+      variant="ghost"
+      class="rounded-full"
+      @click="toggle"
+    />
+  </UTooltip>
+</template>