Assistant

About the Assistant

The assistant answers questions about your documentation through natural language queries. It is embedded directly in your documentation site, so users can find answers quickly and succeed with your product.

When users ask questions, the assistant:

• Searches and retrieves relevant content from your documentation using an MCP server.
• Cites sources with navigable links to take users directly to referenced pages.
• Generates copyable code examples to help users implement solutions from your documentation.

How It Works

The assistant uses a multi-agent architecture:

1. Main Agent - Receives user questions and decides when to search documentation
2. Search Agent - Uses MCP server tools to find relevant content
3. Response Generation - Synthesizes information into helpful, conversational answers

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. You can also connect to an external MCP server if needed.

Quick Start

1. Set up AI Gateway authentication

Pick one of this method:

API key — Create a key in Vercel AI Gateway and add it to your environment:

AI_GATEWAY_API_KEY=your-api-key

OIDC (only on Vercel) — VERCEL_OIDC_TOKEN is injected automatically. Nothing to add in the production. For local dev, run vercel env pull on a linked project.

2. Deploy

Deploy your site — the assistant is available as soon as authentication is configured.

Using the Assistant

Users can interact with the assistant in multiple ways:

Floating Input

On documentation pages, a floating input appears at the bottom of the screen. Users can type their questions directly and press Enter to get answers.

Explain with AI

Each documentation page includes an Explain with AI button in the table of contents sidebar. Clicking this button opens the assistant with the current page as context, asking it to explain the content.

Slideover Chat

When a conversation starts, a slideover panel opens on the right side of the screen. This panel displays the conversation history and allows users to continue asking questions.

Configuration

Configure the assistant through app.config.ts:

export default defineAppConfig({
  assistant: {
    // Show the floating input on documentation pages
    floatingInput: true,

    // Show the "Explain with AI" button in the sidebar
    explainWithAi: true,

    // FAQ questions to display when chat is empty
    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. This helps users discover what they can ask.

Simple Format

export default defineAppConfig({
  assistant: {
    faqQuestions: [
      'How do I install Docus?',
      'How do I customize the theme?',
      'How do I add components to my pages?'
    ]
  }
})

Category Format

Organize questions into categories:

export default defineAppConfig({
  assistant: {
    faqQuestions: [
      {
        category: 'Getting Started',
        items: [
          'How do I install Docus?',
          'What is the project structure?'
        ]
      },
      {
        category: 'Customization',
        items: [
          'How do I change the theme colors?',
          'How do I add a custom logo?'
        ]
      }
    ]
  }
})

Localized Format

For multi-language documentation, provide FAQ questions per locale:

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

Keyboard Shortcuts

Configure the keyboard shortcut for focusing the floating input:

export default defineAppConfig({
  assistant: {
    shortcuts: {
      // Default: 'meta_i' (Cmd+I on Mac, Ctrl+I on Windows)
      focusInput: 'meta_k' // Change to Cmd/Ctrl+K
    }
  }
})

The shortcut format uses underscores to separate keys. Common examples:

• meta_i - Cmd+I (Mac) / Ctrl+I (Windows)
• meta_k - Cmd+K (Mac) / Ctrl+K (Windows)
• ctrl_shift_p - Ctrl+Shift+P

Custom Icons

Customize the icons used by the assistant:

export default defineAppConfig({
  assistant: {
    icons: {
      // Icon for the trigger button and slideover header
      trigger: 'i-lucide-bot',

      // Icon for the "Explain with AI" button
      explain: 'i-lucide-lightbulb'
    }
  }
})

Icons use the Iconify format (e.g., i-lucide-sparkles, i-heroicons-sparkles).

Internationalization

All UI texts are automatically translated based on the user's locale. Docus includes built-in translations for English and French.

The following texts are translated:

• Slideover title and placeholder
• Tooltip texts
• Button labels ("Clear chat", "Close", "Explain with AI")
• Status messages ("Thinking...", "Chat is cleared on refresh")

Disable Features

Disable the Floating Input

Hide the floating input at the bottom of documentation pages:

export default defineAppConfig({
  assistant: {
    floatingInput: false
  }
})

Disable "Explain with AI"

Hide the "Explain with AI" button in the documentation sidebar:

export default defineAppConfig({
  assistant: {
    explainWithAi: false
  }
})

Disable the Assistant Entirely

The assistant is disabled when no authentication is available. To explicitly disable it, remove AI_GATEWAY_API_KEY from your environment:

# AI_GATEWAY_API_KEY=your-api-key

On Vercel with OIDC, remove the auto-injected system environment variable from your project settings.

Advanced Configuration

Configure advanced options in 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'
  }
})

MCP Server Configuration

The assistant uses an MCP server to access your documentation. You have two options:

Use the Built-in MCP Server (Default)

By default, the assistant uses Docus's built-in MCP server at /mcp:

export default defineNuxtConfig({
  assistant: {
    mcpServer: '/mcp'
  }
})

Use an External MCP Server

Connect to any external MCP server by providing a full URL:

export default defineNuxtConfig({
  assistant: {
    mcpServer: 'https://other-docs.example.com/mcp'
  }
})

This is useful when you want the assistant to answer questions from a different documentation source, or when connecting to a centralized knowledge base.

Custom AI Model

The assistant uses google/gemini-3-flash by default. You can change this to any model supported by the AI SDK Gateway:

export default defineNuxtConfig({
  assistant: {
    model: 'anthropic/claude-opus-4.5'
  }
})

Site Name in Responses

The assistant automatically uses your site name in its responses. Configure the site name in nuxt.config.ts:

export default defineNuxtConfig({
  site: {
    name: 'My Documentation'
  }
})

This makes the assistant respond as "the My Documentation assistant" and speak with authority about your specific product.

Programmatic Access

Use the useAssistant composable to control the assistant programmatically:

<script setup>
const { isEnabled, isOpen, open, close, toggle } = useAssistant()

function askQuestion() {
  // Open the assistant with a pre-filled question
  open('How do I configure the theme?', true)
}
</script>

<template>
  <UButton v-if="isEnabled" @click="askQuestion">
    Ask about themes
  </UButton>
</template>

Composable API