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. Install necessary packages

npm install docusaurus-openai-search docusaurus2-dotenv

2. Create an environment file

Create a .env file in your project root:

OPENAI_API_KEY=your_openai_api_key_here

3. Configure docusaurus2-dotenv plugin

Add the plugin to your docusaurus.config.js:

module.exports = {
  // ...other config
  plugins: [
    // ...other plugins
    [
      "docusaurus2-dotenv",
      {
        path: "./.env", // The path to your environment variables
        safe: false, // If false ignore safe-mode, if true load './.env.example', if a string load that file as the sample
        systemvars: false, // Set to true if you would rather load all system variables as well (useful for CI purposes)
        silent: false, // If true, all warnings will be suppressed
        expand: false, // Allows your variables to be "expanded" for reusability within your .env file
        defaults: false, // Adds support for dotenv-defaults. If set to true, uses ./.env.defaults
      },
    ],
  ],
};

4. Swizzle the SearchBar component

Run the swizzle command and select SearchBar to eject:

npm run swizzle

5. Replace the SearchBar component

Replace the content of the swizzled component (typically at src/theme/SearchBar/index.js or index.tsx) with:

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

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

  const apiKey = process.env.OPENAI_API_KEY;

  // AI search configuration
  const aiConfig = {
    // OpenAI API settings
    openAI: {
      apiKey,
      model: "gpt-4.1",
      maxTokens: 10000,
      temperature: 0.3,
    },
    // UI customization
    ui: {
      aiButtonText: "Ask AI",
      modalTitle: "AI Assistant",
      footerText: "Powered by AI",
    },
    // Prompt customization
    prompts: {
      siteName: "Your Site Name",
      // Optional: Customize system prompt
      systemPrompt: "You are a helpful assistant. Your goal is to provide detailed, accurate information about the documentation provided."
    },
  };
  
  return <DocusaurusAISearch algoliaConfig={algolia} aiConfig={aiConfig} />;
}

Crafting Effective System Prompts

A well-crafted system prompt is crucial for getting high-quality answers from the AI assistant. Here's a guide to creating effective system prompts for documentation:

System Prompt Structure

An effective system prompt typically includes:

1. Role Definition: Define the AI's role and expertise
2. Response Guidelines: Set clear expectations for answer quality and style
3. Domain Knowledge: Provide key facts about your product/platform
4. Formatting Preferences: Specify how answers should be formatted

Example System Prompt Template

Here's an annotated example of an effective system prompt:

const systemPrompt =
  // Role definition - clearly establish the assistant's identity and purpose
  "You are a helpful [PRODUCT] expert assistant. Your goal is to provide detailed, accurate information about [PRODUCT]'s [FEATURES] to [TARGET USERS].\n\n" +
  
  // Response guidelines - establish clear expectations for answers
  "RESPONSE GUIDELINES:\n" +
  "1. BE HELPFUL: Always try to provide SOME guidance, even when the documentation doesn't contain a perfect answer.\n" +
  "2. PRIORITIZE USER SUCCESS: Focus on helping the user accomplish their task with [PRODUCT].\n" +
  "3. USE DOCUMENTATION FIRST: Base your answers primarily on the provided documentation snippets.\n" +
  "4. CODE EXAMPLES ARE CRUCIAL: Always include code snippets from the documentation when available, as they're extremely valuable to developers.\n" +
  "5. INFERENCE IS ALLOWED: When documentation contains related but not exact information, use reasonable inference to bridge gaps based on standard [PRODUCT] patterns.\n" +
  "6. BE HONEST: If you truly can't provide an answer, suggest relevant [PRODUCT] concepts or documentation sections that might help instead.\n" +
  "7. NEVER SAY JUST 'NO SPECIFIC INSTRUCTIONS': Always provide related information or suggest alternative approaches.\n\n" +
  
  // Domain knowledge - provide key facts about your product/platform
  "ABOUT [PRODUCT]:\n" +
  "- [KEY FACT 1 ABOUT YOUR PRODUCT]\n" +
  "- [KEY FACT 2 ABOUT YOUR PRODUCT]\n" +
  "- [KEY FACT 3 ABOUT YOUR PRODUCT]\n" +
  "- [KEY TECHNICAL DETAILS THAT HELP ANSWER COMMON QUESTIONS]";

Best Practices

1. Be specific about response format: Explicitly state if you want code examples, step-by-step instructions, etc.
2. Include critical domain knowledge: Add key facts that help the AI understand your product's unique aspects
3. Set clear guardrails: Define what the AI should do when it doesn't have a perfect answer
4. Balance brevity and detail: Include enough context without overwhelming the model
5. Focus on user success: Orient the prompt toward solving user problems, not just providing information

Tips for Technical Documentation

For technical documentation, consider:

1. Emphasize code examples: Instruct the AI to prioritize showing code snippets when relevant
2. Address common user scenarios: Mention key use cases your users frequently encounter
3. Clarify technical terminology: If your product uses specific technical terms, include brief definitions
4. Reference documentation structure: If your docs have a specific organization, explain it briefly

When implementing the system prompt in your SearchBar component:

// In your SearchBar component
const systemPrompt = 
  "You are a helpful [YOUR PRODUCT] expert assistant...[rest of your prompt]";

const aiConfig = {
  // ...other config
  prompts: {
    siteName: "Your Site Name",
    systemPrompt: systemPrompt,
  },
};

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.