Docusaurus Plugin

Add an AI-powered chat assistant to your Docusaurus documentation site.

Open Source

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

Installation

npm install vetradocs-docusaurus

Prerequisites

Before using this plugin, you need:

A Docusaurus site (v2.0+ or v3.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.

Quick Start

Step 1: Create Root Component

Swizzle the Root component or create src/theme/Root.js:

import React from 'react';
import { VetradocsChat, VetradocsFloatingBar } from 'vetradocs-docusaurus';

// Import styles
import 'vetradocs-docusaurus/dist/theme/VetradocsChat/styles.css';
import 'vetradocs-docusaurus/dist/theme/VetradocsFloatingBar/styles.css';

export default function Root({ children }) {
  return (
    <>
      {children}
      <VetradocsFloatingBar 
        apiEndpoint="https://your-backend.com"
        apiKey="your-api-key"
        accentColor="#f97316"
      />
      <VetradocsChat 
        apiEndpoint="https://your-backend.com"
        apiKey="your-api-key"
        title="AI Assistant"
        accentColor="#f97316"
      />
    </>
  );
}

Step 2: Build the Search Index

Add a post-build script to generate the search index:

{
  "scripts": {
    "build": "docusaurus build && npx vetradocs-build-docusaurus",
    "build:index": "vetradocs-build-docusaurus"
  }
}

This creates static/search-index.json.

Component Reference

VetradocsFloatingBar

The floating input bar at the bottom of the screen.

Prop	Type	Default	Description
`apiEndpoint`	`string`	`/api/chat`	Backend API URL
`apiKey`	`string`	`""`	API key for authentication
`indexPath`	`string`	`/search-index.json`	Path to search index
`placeholder`	`string`	`"Ask a question..."`	Input placeholder
`accentColor`	`string`	`"#f97316"`	Primary theme color
`position`	`string`	`"bottom-center"`	`bottom-center`, `bottom-right`, `bottom-left`

VetradocsChat

The slide-out chat sidebar.

Prop	Type	Default	Description
`apiEndpoint`	`string`	`/api/chat`	Backend API URL
`apiKey`	`string`	`""`	API key for authentication
`indexPath`	`string`	`/search-index.json`	Path to search index
`title`	`string`	`"AI Assistant"`	Title in chat header
`accentColor`	`string`	`"#f97316"`	Primary theme color

Hook API

For custom implementations, use the useVetradocs hook:

import { useVetradocs } from 'vetradocs-docusaurus';

function MyComponent() {
  const {
    // State
    isOpen,       // boolean - Chat sidebar open state
    messages,     // Message[] - Chat history
    input,        // string - Current input value
    loading,      // boolean - Whether AI is responding
    
    // Actions
    sendMessage,  // (text: string) => Promise<void>
    clearChat,    // () => void
    toggleChat,   // () => void
    setInput,     // (value: string) => void
  } = useVetradocs({
    apiEndpoint: 'https://your-backend.com',
    apiKey: 'your-api-key',
    indexPath: '/search-index.json',
  });

  return (
    <button onClick={() => sendMessage('Hello!')}>
      Ask AI
    </button>
  );
}

Configuration Examples

Minimal Setup

<VetradocsFloatingBar apiEndpoint="https://api.example.com" />
<VetradocsChat apiEndpoint="https://api.example.com" />

Full Configuration

<VetradocsFloatingBar 
  apiEndpoint="https://api.example.com"
  apiKey="secret-key-123"
  indexPath="/search-index.json"
  placeholder="What would you like to know?"
  accentColor="#8b5cf6"
  position="bottom-right"
/>
<VetradocsChat 
  apiEndpoint="https://api.example.com"
  apiKey="secret-key-123"
  indexPath="/search-index.json"
  title="Documentation AI"
  accentColor="#8b5cf6"
/>

Styling

Custom Accent Color

Use any CSS color:

<VetradocsFloatingBar accentColor="#10b981" />
<VetradocsChat accentColor="#10b981" />

Custom CSS

Override styles in your custom.css:

.vetradocs-floating-bar {
  /* Customize the floating bar */
}

.vetradocs-chat-sidebar {
  /* Customize the chat sidebar */
}

Troubleshooting

Components don't appear

Ensure styles are imported
Check that Root.js is in src/theme/
Restart the dev server

AI says "I don't know"

Rebuild the search index
Verify your backend is running
Check apiEndpoint points to the correct URL

CORS errors

Ensure backend FRONTEND_URL matches your Docusaurus URL
Include protocol (http:// or https://)

Docusaurus Plugin

Docusaurus Plugin

Installation

Prerequisites

Setting Up the Backend

Quick Start

Step 1: Create Root Component

Step 2: Build the Search Index

Component Reference

VetradocsFloatingBar

VetradocsChat

Hook API

Configuration Examples

Minimal Setup

Full Configuration

Styling

Custom Accent Color

Custom CSS

Troubleshooting

Components don't appear

AI says "I don't know"

CORS errors

Links

On this page

How can I help?