VitePress Plugin

Add an AI-powered chat assistant to your VitePress documentation site in minutes.

Open Source

This plugin is MIT licensed and free to use.
View on GitHub · npm package

Installation

npm install vetradocs-vitepress

Prerequisites

Before using this plugin, you need:

A VitePress site (v1.0+)
A backend service to handle AI requests

Setting Up the Backend

Run our CLI to create a backend:

npx create-vetradocs-backend@latest

Choose Node.js (Express) (recommended) or Cloudflare Workers, then deploy it.

See Backend Setup for detailed instructions.

Configuration

After deploying your backend, add these environment variables to your VitePress project:

Create .env in your VitePress root:

VITE_VETRADOCS_BACKEND_URL=https://your-backend-url.com
VITE_VETRADOCS_API_KEY=your-generated-api-key

The plugin automatically reads these variables. No additional configuration needed!

Quick Start

Step 1: Create a Custom Layout

Create .vitepress/theme/Layout.vue:

<script setup>
import DefaultTheme from 'vitepress/theme';
import { VetradocsChat, VetradocsFloatingBar } from 'vetradocs-vitepress/theme';

const { Layout } = DefaultTheme;
</script>

<template>
  <Layout>
    <template #layout-bottom>
      <VetradocsFloatingBar 
        accent-color="#f97316"
        placeholder="Ask AI about the docs..."
      />
      <VetradocsChat 
        title="AI Assistant"
        accent-color="#f97316"
      />
    </template>
  </Layout>
</template>

Step 2: Register the Layout

Update .vitepress/theme/index.ts:

import Layout from './Layout.vue';

export default {
  Layout,
  // ... other theme config
};

Step 3: Build the Search Index

The AI needs to "read" your documentation. Build the search index:

npx vetradocs-build --docs ./docs --output ./docs/public/search-index.json

Add this to your package.json:

{
  "scripts": {
    "docs:build-index": "vetradocs-build --docs ./docs --output ./docs/public/search-index.json",
    "docs:build": "npm run docs:build-index && vitepress build docs"
  }
}

Component Reference

VetradocsFloatingBar

The floating input bar at the bottom of the screen.

Prop	Type	Default	Description
`placeholder`	`string`	`"Ask a question..."`	Input placeholder text
`accentColor`	`string`	`"#f97316"`	Primary theme color
`position`	`string`	`"bottom-center"`	Position: `bottom-center`, `bottom-right`, `bottom-left`
`shortcut`	`string`	`"i"`	Keyboard shortcut to focus (Ctrl/Cmd + key)

VetradocsChat

The slide-out chat sidebar.

Prop	Type	Default	Description
`title`	`string`	`"AI Assistant"`	Title in the chat header
`accentColor`	`string`	`"#f97316"`	Primary theme color

Composable API

For custom implementations, use the useVetradocs composable:

import { useVetradocs } from 'vetradocs-vitepress';

const {
  // State
  isOpen,       // Ref<boolean> - Chat sidebar open state
  messages,     // Ref<Message[]> - Chat history
  input,        // Ref<string> - Current input value
  loading,      // Ref<boolean> - Whether AI is responding
  
  // Actions
  sendMessage,  // (text: string) => Promise<void>
  clearChat,    // () => void - Clear all messages
  toggleChat,   // () => void - Open/close sidebar
  searchDocs,   // (query: string) => Promise<SearchResult[]>
} = useVetradocs({
  apiEndpoint: '/api/chat',
  indexPath: '/search-index.json',
});

Message Type

interface Message {
  role: 'user' | 'assistant';
  content: string;
}

SearchResult Type

interface SearchResult {
  id: string;
  title: string;
  content: string;
  path: string;
  score: number;
}

CLI Reference

vetradocs-build

Builds the search index for your documentation.

npx vetradocs-build [options]

Options:
  --docs <path>     Path to docs directory (default: ./docs)
  --output <path>   Output path for index (default: ./docs/public/search-index.json)
  --help            Show help

Example:

npx vetradocs-build --docs ./src/docs --output ./public/search-index.json

Styling & Theming

Custom Accent Color

Pass a CSS color to the accentColor prop:

<VetradocsFloatingBar accent-color="#8b5cf6" />
<VetradocsChat accent-color="#8b5cf6" />

CSS Variables

You can override styles using CSS:

/* In your custom CSS */
.vetradocs-floating-bar {
  --vd-accent: #8b5cf6;
  --vd-bg: #18181b;
  --vd-text: #fafafa;
}

Troubleshooting

Chat doesn't open

Check browser console for errors
Verify the search index exists at /search-index.json
Ensure components are in the #layout-bottom slot

AI says "I don't know"

Rebuild the search index: npx vetradocs-build
Check that your backend is running
Verify environment variables are set

CORS errors

Ensure your backend's FRONTEND_URL matches your VitePress dev server URL.

VitePress Plugin

VitePress Plugin

Installation

Prerequisites

Setting Up the Backend

Configuration

Quick Start

Step 1: Create a Custom Layout

Step 2: Register the Layout

Step 3: Build the Search Index

Component Reference

VetradocsFloatingBar

VetradocsChat

Composable API

Message Type

SearchResult Type

CLI Reference

vetradocs-build

Styling & Theming

Custom Accent Color

CSS Variables

Troubleshooting

Chat doesn't open

AI says "I don't know"

CORS errors

Links

On this page

How can I help?