Docusaurus OpenAI Search

AI-enhanced search component for Docusaurus using OpenAI's API to provide AI-powered answers based on your documentation content.

Features

• Drop-in replacement for Docusaurus's default Algolia DocSearch
• AI-powered answer generation based on search results
• Extracts content from documentation pages for contextual answers
• Customizable prompts, models, and UI
• Full TypeScript support

Installation

npm install docusaurus-openai-search

Setup

1. Configure your Docusaurus config

Add your OpenAI API key to your docusaurus.config.js file:

module.exports = {
  // ...other config
  customFields: {
    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
  },
  scripts: [
    {
      src: '/docusaurus-openai-search.js',
      async: true,
    },
  ],
};

2. Expose the OpenAI API key

You need to add the environment variables plugin to your configuration:

Option A: Using the included plugin (recommended)

The package includes a plugin that you can import directly:

// In your docusaurus.config.js
const { envPlugin } = require('docusaurus-openai-search');
// Or using ES modules
// import { envPlugin } from 'docusaurus-openai-search';

module.exports = {
  // ...other config
  plugins: [
    // ...other plugins
    envPlugin,
  ],
};

Option B: Manually create the plugin

Create a file named docusaurus-env-variables-plugin.js in your project root:

// A Docusaurus plugin to provide environment variables to the client

const plugin = function (context, options) {
  return {
    name: "docusaurus-env-variables-plugin",
    injectHtmlTags() {
      return {
        headTags: [
          {
            tagName: "script",
            innerHTML: `window.OPENAI_API_KEY = "${process.env.OPENAI_API_KEY || ""}"`,
          },
        ],
      };
    },
  };
};

module.exports = plugin;
module.exports.default = plugin;

Then add the plugin to your docusaurus.config.js:

const envPlugin = require('./docusaurus-env-variables-plugin');

module.exports = {
  // ...other config
  plugins: [
    // ...other plugins
    envPlugin,
  ],
};

3. Add the swizzled theme component

Create a file at src/theme/SearchBar/index.js:

import React from 'react';
import { DocusaurusAISearch } from 'docusaurus-openai-search';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

export default function SearchBar() {
  const { 
    siteConfig: { 
      themeConfig: { algolia },
      customFields,
    },
  } = useDocusaurusContext();

  const aiConfig = {
    openAI: {
      apiKey: customFields.OPENAI_API_KEY,
      model: 'gpt-4.1',
      maxTokens: 2000,
      temperature: 0.5,
    },
    ui: {
      aiButtonText: 'Ask AI about this',
      modalTitle: 'AI Answer',
    },
    prompts: {
      siteName: 'Your Site Name',
    },
  };

  return <DocusaurusAISearch 
    algoliaConfig={algolia} 
    aiConfig={aiConfig} 
  />;
}

API Reference

DocusaurusAISearch Component

The main component that replaces the default Docusaurus search component.

Props

AlgoliaConfig Object

The algoliaConfig prop contains all the standard Algolia DocSearch configuration options:

AIConfig Object

The aiConfig prop configures the AI-powered search features:

OpenAI Options

The openAI object configures the OpenAI API settings:

UI Options

The ui object customizes the appearance and text of UI elements:

Prompt Options

The prompts object configures how prompts are generated for the AI:

Event Callbacks

Custom Prompt Templates

You can fully customize the system and user prompts with custom templates.

System Prompt

The default system prompt (when no custom prompt is provided):

You are a helpful {siteName} assistant. Your goal is to provide detailed, accurate information about {siteName} based on the documentation provided.

RESPONSE GUIDELINES:
1. BE HELPFUL: Always try to provide SOME guidance, even when the documentation doesn't contain a perfect answer.
2. PRIORITIZE USER SUCCESS: Focus on helping the user accomplish their task.
3. USE DOCUMENTATION FIRST: Base your answers primarily on the provided documentation snippets.
4. CODE EXAMPLES ARE CRUCIAL: Always include code snippets from the documentation when available.
5. INFERENCE IS ALLOWED: When documentation contains related but not exact information, use reasonable inference to bridge gaps.
6. BE HONEST: If you truly can't provide an answer, suggest relevant concepts or documentation sections that might help instead.
7. FORMAT YOUR RESPONSE: Use markdown formatting for headings, code blocks, and lists to make your response easy to read.

User Prompt

The default user prompt contains the following elements:

• The user's search query
• Content from the most relevant documentation sections
• Source references to the original documentation pages

When creating a custom user prompt, you can use these template variables:

• {query} - The user's search query
• {context} - The extracted documentation content
• {sources} - References to the source documentation

Example custom user prompt:

Answer this question: {query}

Here's relevant documentation:
{context}

Sources:
{sources}

Keep your answer under 300 words and include code examples when available.

Utility Functions

trackAIQuery

function trackAIQuery(query: string, success: boolean = true): void

Tracks AI queries for analytics purposes. By default, this logs to the console and sends a Google Analytics event if available.

Parameters:

• query: The search query string
• success: Whether the query was successful (default: true)

Security Considerations

• Never expose your OpenAI API key directly in client-side code without rate limiting
• Consider implementing a server-side proxy for OpenAI requests
• Set usage limits on your OpenAI API key to prevent unexpected costs
• For production environments, implement proper authentication and rate-limiting

Troubleshooting

OpenAI API Key Issues

If you encounter issues with the OpenAI API key:

1. Verify that your API key is correctly set in docusaurus.config.js
2. Check that your static/docusaurus-openai-search.js file is correctly set up
3. Inspect the console for any error messages related to the OpenAI API

Document Content Retrieval Issues

If the AI cannot retrieve document content:

1. Ensure your documentation pages follow standard Docusaurus HTML structure
2. Check that the server allows the browser to fetch documentation pages via JavaScript
3. Try enabling the highlightCode option if code blocks are important to your documentation

License

MIT

Credits

Built on top of Docusaurus and Algolia DocSearch.