Skip to main content

Overview

The AI Assistant is a built-in chat interface that provides intelligent, contextual answers to user questions about your documentation. It uses the Model Context Protocol (MCP) to search and retrieve relevant content, then generates helpful responses with source citations and code examples.
The assistant requires an AI Gateway API key to function. Without this key, the assistant components will be automatically disabled.

How It Works

The assistant uses a multi-agent architecture powered by the AI SDK:
  1. User Query - Users ask questions through the floating input or slideover interface
  2. MCP Tools - The AI uses your built-in MCP server to search and retrieve documentation pages
  3. Response Generation - The AI synthesizes information into conversational answers with citations
  4. Streaming UI - Responses stream in real-time with syntax-highlighted code blocks
By default, the assistant connects to your documentation’s built-in MCP server at /mcp, giving it access to all your pages without additional configuration.

Quick Start

1

Get an API Key

Visit Vercel AI Gateway and create an API key. AI Gateway supports multiple providers (OpenAI, Anthropic, Google, and more) through a unified API.
2

Add Environment Variable

Set your API key in your environment:
.env
AI_GATEWAY_API_KEY=your-api-key-here
3

Deploy and Test

That’s it! The assistant is automatically enabled when the API key is detected. Deploy your site and look for the floating input at the bottom of documentation pages.

User Interface Components

Floating Input

A compact input field appears at the bottom center of documentation pages, allowing users to quickly ask questions without opening a panel. Features:
  • Auto-hides when the chat slideover is open
  • Expands on focus for better typing experience
  • Keyboard shortcut: Cmd+I (Mac) or Ctrl+I (Windows)
  • Press Escape to blur the input

Chat Slideover

When users submit a question, a side panel opens displaying the conversation. The panel includes:
  • Streaming responses with real-time text generation
  • Syntax-highlighted code blocks using Shiki
  • Source citations linking back to relevant documentation pages
  • FAQ suggestions when the chat is empty
  • Clear chat button to start a fresh conversation

Explain with AI Button

Each documentation page includes an “Explain with AI” button in the sidebar that opens the assistant with the current page as context.

Configuration

Basic Options

Configure the assistant in nuxt.config.ts:
nuxt.config.ts
export default defineNuxtConfig({
  assistant: {
    // AI model (uses AI SDK Gateway format)
    model: 'google/gemini-3-flash',
    
    // MCP server path or URL
    mcpServer: '/mcp',
    
    // API endpoint path
    apiPath: '/__docus__/assistant'
  }
})

Module Options

OptionTypeDefaultDescription
apiPathstring/__docus__/assistantAPI endpoint path for the chat
mcpServerstring/mcpMCP server path or full URL
modelstringgoogle/gemini-3-flashAI model identifier for AI SDK Gateway

App Configuration

Customize the UI and behavior in app.config.ts:
app.config.ts
export default defineAppConfig({
  assistant: {
    // Show floating input on documentation pages
    floatingInput: true,
    
    // Show "Explain with AI" button in sidebar
    explainWithAi: true,
    
    // FAQ questions (see below for formats)
    faqQuestions: [],
    
    // Keyboard shortcuts
    shortcuts: {
      focusInput: 'meta_i'
    },
    
    // Custom icons
    icons: {
      trigger: 'i-lucide-sparkles',
      explain: 'i-lucide-brain'
    }
  }
})

FAQ Questions

Display suggested questions when the chat is empty to help users discover capabilities.

Simple Array

app.config.ts
export default defineAppConfig({
  assistant: {
    faqQuestions: [
      'How do I get started?',
      'How do I customize the theme?',
      'How do I deploy my site?'
    ]
  }
})

Categorized Questions

app.config.ts
export default defineAppConfig({
  assistant: {
    faqQuestions: [
      {
        category: 'Getting Started',
        items: [
          'How do I install the framework?',
          'What is the project structure?'
        ]
      },
      {
        category: 'Customization',
        items: [
          'How do I change colors?',
          'How do I add custom components?'
        ]
      }
    ]
  }
})

Localized Questions

export default defineAppConfig({
  assistant: {
    faqQuestions: {
      en: [
        { 
          category: 'Getting Started', 
          items: ['How do I install?'] 
        }
      ],
      fr: [
        { 
          category: 'Démarrage', 
          items: ['Comment installer ?'] 
        }
      ]
    }
  }
})

MCP Server Configuration

The assistant requires an MCP server to access your documentation content.

Built-in MCP Server (Default)

Use Docus’s built-in MCP server that automatically exposes all your documentation pages:
nuxt.config.ts
export default defineNuxtConfig({
  assistant: {
    mcpServer: '/mcp'
  }
})
Ensure the MCP server is enabled in your configuration. If you’ve disabled it or customized the path, update the mcpServer option accordingly.

External MCP Server

Connect to any external MCP server by providing a full URL:
nuxt.config.ts
export default defineNuxtConfig({
  assistant: {
    mcpServer: 'https://other-docs.example.com/mcp'
  }
})
This allows the assistant to answer questions from different documentation sources or a centralized knowledge base.

AI Model Selection

The assistant uses google/gemini-3-flash by default for fast, cost-effective responses. You can change to any model supported by AI SDK Gateway:
export default defineNuxtConfig({
  assistant: {
    model: 'google/gemini-3-flash'
  }
})

Customization

Site Name in Responses

The assistant automatically uses your site name in responses. Configure it in nuxt.config.ts:
nuxt.config.ts
export default defineNuxtConfig({
  site: {
    name: 'My Documentation'
  }
})
The assistant will respond as “the My Documentation assistant” and speak with authority about your specific product.

System Prompt

To customize the AI’s behavior and personality, you can override the system prompt by creating a custom server handler:
server/api/__docus__/assistant.ts
import { streamText } from 'ai'

function getSystemPrompt(siteName: string) {
  return `You are a helpful assistant for ${siteName}.
  
  Key guidelines:
  - Be concise and friendly
  - Always cite your sources
  - Provide code examples when relevant
  - Never use markdown headings
  - Use **bold** for emphasis`
}

export default defineEventHandler(async (event) => {
  // Your custom implementation
})

Keyboard Shortcuts

Customize the keyboard shortcut for focusing the floating input:
app.config.ts
export default defineAppConfig({
  assistant: {
    shortcuts: {
      focusInput: 'meta_k' // Changes to Cmd+K / Ctrl+K
    }
  }
})
Common shortcut formats:
  • meta_i - Cmd+I (Mac) / Ctrl+I (Windows)
  • meta_k - Cmd+K (Mac) / Ctrl+K (Windows)
  • ctrl_shift_p - Ctrl+Shift+P

Custom Icons

Replace the default icons with any Iconify icon:
app.config.ts
export default defineAppConfig({
  assistant: {
    icons: {
      trigger: 'i-lucide-bot',
      explain: 'i-lucide-lightbulb'
    }
  }
})
Browse available icons at Iconify.

Programmatic Control

Use the useAssistant composable to control the assistant from your components:
<script setup>
const { 
  isEnabled,     // Whether assistant is enabled (API key present)
  isOpen,        // Whether slideover is open
  isExpanded,    // Whether panel is expanded
  messages,      // Chat message history
  faqQuestions,  // FAQ questions from config
  open,          // Open assistant
  close,         // Close assistant
  toggle,        // Toggle open/closed
  clearMessages  // Clear chat history
} = useAssistant()

// Open with a pre-filled question
function askAboutThemes() {
  open('How do I customize the theme?', true)
}

// Open without clearing previous messages
function continueChat() {
  open('Tell me more about components')
}
</script>

<template>
  <div>
    <UButton 
      v-if="isEnabled" 
      @click="askAboutThemes"
    >
      Ask about themes
    </UButton>
    
    <UButton @click="toggle">
      {{ isOpen ? 'Close' : 'Open' }} Assistant
    </UButton>
  </div>
</template>

Composable API Reference

PropertyTypeDescription
isEnabledComputedRef<boolean>Whether assistant is enabled (API key present)
isOpenRef<boolean>Whether slideover is open
isExpandedRef<boolean>Whether panel is in expanded mode
isMobileRef<boolean>Whether viewport is mobile size
panelWidthComputedRef<number>Current panel width (360 or 520px)
messagesRef<UIMessage[]>Chat message history
pendingMessageRef<string?>Message waiting to be sent
faqQuestionsComputedRef<FaqCategory[]>FAQ questions from config
open(message?, clear?)FunctionOpen assistant with optional message
close()FunctionClose assistant slideover
toggle()FunctionToggle open/closed state
toggleExpanded()FunctionToggle panel width
clearMessages()FunctionClear conversation history
clearPending()FunctionClear pending message

Disabling Features

Disable Floating Input

app.config.ts
export default defineAppConfig({
  assistant: {
    floatingInput: false
  }
})

Disable “Explain with AI” Button

app.config.ts
export default defineAppConfig({
  assistant: {
    explainWithAi: false
  }
})

Disable Assistant Entirely

Simply remove the environment variable:
.env
# Comment out or remove
# AI_GATEWAY_API_KEY=your-api-key
When disabled, all assistant components are replaced with a disabled placeholder component.

Internationalization

All UI text is automatically translated based on the user’s locale. Docus includes built-in translations for English and French. Translated elements:
  • Slideover title and placeholder text
  • Button labels (“Clear chat”, “Close”, “Explain with AI”)
  • Tooltip texts
  • Status messages (“Thinking…”, “Chat is cleared on refresh”)
To add more languages, contribute to the Docus i18n files.

Dependencies

The assistant module requires these packages (automatically installed with Docus):
package.json
{
  "dependencies": {
    "@ai-sdk/mcp": "latest",
    "@ai-sdk/vue": "latest",
    "@ai-sdk/gateway": "latest",
    "ai": "latest",
    "shiki": "latest",
    "shiki-stream": "latest",
    "motion-v": "latest"
  }
}

Troubleshooting

Assistant not appearing? Check that:
  1. AI_GATEWAY_API_KEY is set in your environment
  2. Your site is running in production mode or has the key in .env
  3. The MCP server is enabled and accessible at the configured path
API key in version control: Never commit your .env file or expose your API key in client-side code. Use environment variables in your deployment platform.

Advanced: Custom Implementation

The assistant module is located in modules/assistant/ and can be customized:
  • Components: runtime/components/ - Vue components for UI
  • Composables: runtime/composables/useAssistant.ts - State management
  • API Handler: runtime/server/api/search.ts - Streaming chat endpoint
  • Types: runtime/types.ts - TypeScript definitions
You can override any component or create a completely custom implementation using the same architecture.

Build docs developers (and LLMs) love