Docusaurus AI Chat Plugin

A powerful AI-powered contextual chat plugin for Docusaurus that brings intelligent, RAG-based assistance to your documentation. Built with TypeScript, React, and OpenAI-compatible APIs.

✨ Features

• 🤖 AI-Powered Chat - Contextual Q&A based on your documentation
• 📚 RAG (Retrieval Augmented Generation) - Semantic search with embeddings
• 🎯 Smart Citations - Clickable source links for every answer
• ⚡ Real-time Streaming - SSE support for token-by-token responses
• 🔒 Security First - Prompt injection guards and rate limiting
• 🎨 Theme-Aware UI - Respects Docusaurus dark/light mode
• 📦 Zero Config - Works out of the box with sensible defaults
• 🔌 Flexible Deployment - Local server or external endpoint
• ♻️ Incremental Indexing - Smart caching to speed up rebuilds

📦 Installation

Note: This plugin is not yet published to npm. Use one of the following methods:

Option 1: Install from GitHub (after pushing)

npm install edujbarrios/docusaurus-plugin-ai-chat
# or
yarn add edujbarrios/docusaurus-plugin-ai-chat

Option 2: Local Development

# Clone the repository
git clone https://github.com/edujbarrios/docusaurus-plugin-ai-chat.git
cd docusaurus-plugin-ai-chat

# Build the plugin
npm install
npm run build

# Link locally
npm link

# In your Docusaurus project
npm link docusaurus-plugin-ai-chat

Option 3: Publish to npm (for maintainers)

# Login to npm
npm login

# Publish
npm publish

# Then users can install with:
# npm install docusaurus-plugin-ai-chat

🚀 Quick Start

1. Add Plugin to Config

Edit your docusaurus.config.js:

module.exports = {
  plugins: [
    [
      'docusaurus-plugin-ai-chat',
      {
        // Required: OpenAI-compatible API settings
        provider: 'openai-compatible',
        apiKey: process.env.AI_API_KEY,
        baseUrl: process.env.AI_BASE_URL || 'https://api.openai.com/v1',
        model: 'gpt-4o-mini',
        embeddingsModel: 'text-embedding-3-small',
        
        // Optional: Customize behavior
        chunkSizeTokens: 800,
        chunkOverlapTokens: 80,
        topK: 6,
        preferCurrentPage: true,
        enableStreaming: true,
      },
    ],
  ],
};

2. Set Environment Variables

Create a .env file:

AI_API_KEY=your-openai-api-key
AI_BASE_URL=https://api.openai.com/v1

3. Build Your Site

npm run build

During build, the plugin will:

• Extract content from MDX files
• Generate semantic chunks
• Create embeddings
• Build search index at .docusaurus/ai-index.json

4. Run Your Site

npm run start

You'll see a floating chat button in the bottom-right corner! 🎉

⚙️ Configuration Options

Option	Type	Default	Description
provider	'openai-compatible' | 'ollama'	'openai-compatible'	LLM provider type
apiKey	string	-	API key for authentication
baseUrl	string	'https://api.openai.com/v1'	Base URL for API
model	string	'gpt-4o-mini'	Model for chat completions
embeddingsModel	string	'text-embedding-3-small'	Model for embeddings
chunkSizeTokens	number	800	Size of text chunks (in tokens)
chunkOverlapTokens	number	80	Overlap between chunks
topK	number	6	Number of chunks to retrieve
preferCurrentPage	boolean	true	Boost current page in results
enableStreaming	boolean	true	Enable SSE streaming
index.type	'json' | 'sqlite'	'json'	Index storage format
index.path	string	'.docusaurus/ai-index.json'	Index file path
endpointUrl	string | null	null	External API endpoint (see below)
maxTokensContext	number	4000	Max tokens in context
enableRateLimit	boolean	true	Enable rate limiting
rateLimitPerMinute	number	20	Requests per minute per IP
contentDirs	string[]	['docs']	Directories to index

🏗️ Architecture

Build-Time Flow

MDX Files → Extract Content → Chunk Text → Generate Embeddings → Persist Index

1. loadContent() - Scans MDX files in content directories
2. Extract - Parses frontmatter, headings, code blocks, and text
3. Chunk - Splits content into semantic chunks with overlap
4. Embed - Generates vector embeddings via OpenAI API
5. Index - Saves to JSON (or SQLite) with deduplication

Runtime Flow

User Query → Embed Query → Vector Search → Retrieve TopK → LLM Generation → Response + Citations

1. Query Embedding - Convert user question to vector
2. Similarity Search - Find most relevant chunks (cosine similarity)
3. Context Building - Assemble retrieved chunks
4. Prompt Construction - Add security guards and system prompt
5. LLM Call - Generate answer with citations
6. Stream - Return tokens via SSE (if enabled)

🔌 Deployment Modes

Mode 1: Local Server (Default)

The plugin includes a built-in Express server:

// In your server code (e.g., server.js)
import { createHandler } from 'docusaurus-plugin-ai-chat/lib/server/handler';
import path from 'path';

const app = createHandler(
  {
    provider: 'openai-compatible',
    apiKey: process.env.AI_API_KEY,
    baseUrl: process.env.AI_BASE_URL,
    model: 'gpt-4o-mini',
    embeddingsModel: 'text-embedding-3-small',
    // ... other options
  },
  path.join(__dirname, '.docusaurus/ai-index.json')
);

app.listen(3001, () => {
  console.log('AI Chat API running on http://localhost:3001');
});

The client will call /api/ai-chat by default.

Mode 2: External Endpoint

Use an external API (e.g., Vercel, AWS Lambda):

plugins: [
  [
    'docusaurus-plugin-ai-chat',
    {
      // ... API credentials for indexing only
      endpointUrl: 'https://your-api.vercel.app/api/ai-chat',
      // ... other options
    },
  ],
],

Your endpoint should accept POST requests with:

{
  "message": "How do I install this?",
  "currentRoute": "/docs/intro",
  "history": []
}

And return:

{
  "answer": "To install, run `npm install ...`",
  "citations": [
    {
      "route": "/docs/intro",
      "anchor": "installation",
      "title": "Installation",
      "snippet": "Run the following command..."
    }
  ]
}

🔐 Security Notes

Prompt Injection Protection

The plugin implements multiple layers of defense:

1. System Prompt - Instructs model to ignore embedded instructions
2. Input Sanitization - Removes control characters, limits length
3. Context Sanitization - Escapes dangerous patterns
4. Detection - Flags suspicious patterns in user input

Rate Limiting

Built-in rate limiting prevents abuse:

• Default: 20 requests/minute per IP
• Configurable via rateLimitPerMinute
• Can be disabled with enableRateLimit: false

API Key Security

⚠️ NEVER expose API keys in client code!

• Use environment variables
• Keep keys in .env (gitignored)
• For production, use external endpoint mode
• Consider API key rotation

🎨 Customization

Styling

Override CSS variables in your custom CSS:

[data-theme='light'] {
  --ifm-color-primary: #your-color;
}

[data-theme='dark'] {
  --ifm-color-primary: #your-dark-color;
}

The chat panel automatically respects these theme variables.

Quick Actions

Customize the quick action buttons by forking the component or creating a theme wrapper.

🐛 Troubleshooting

"No index found"

Solution: Run npm run build to generate the index.

"API key not set"

Solution: Ensure AI_API_KEY is in your .env and loaded:

// docusaurus.config.js
require('dotenv').config();

"Rate limit exceeded"

Solution: Increase rateLimitPerMinute or disable with enableRateLimit: false.

Embeddings too slow

Solutions:

• Use a smaller embeddings model
• Enable incremental indexing (automatic)
• Use SQLite index for large sites
• Reduce chunkSizeTokens

Poor answer quality

Solutions:

• Increase topK to retrieve more context
• Enable preferCurrentPage for page-specific queries
• Adjust chunkSizeTokens and chunkOverlapTokens
• Use a more powerful model (e.g., gpt-4)

🧪 Example Implementation

See the /example directory for a complete working example.

📝 API Reference

Plugin Lifecycle

• loadContent() - Collects MDX files
• contentLoaded() - Processes and indexes content
• getClientModules() - Injects UI components
• postBuild() - Final validation

Server API

POST /api/ai-chat

Non-streaming chat endpoint.

POST /api/ai-chat/stream

Streaming chat endpoint (SSE).

GET /api/ai-chat/health

Health check endpoint.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

👤 Author

Eduardo J. Barrios (edujbarrios)

• GitHub: @edujbarrios

🙏 Acknowledgments

• Built with Docusaurus
• Powered by OpenAI
• Inspired by modern RAG implementations

📊 Compatibility

• Docusaurus: v2.x and v3.x
• Node.js: >= 18.0.0
• React: v17.x and v18.x

🔗 Links

• Documentation
• Issues
• Changelog