How to Add AI Chatbot to Docusaurus

Why Add a Chatbot to Your Technical Documentation?

Technical documentation can span hundreds of pages. Even with good search and navigation, users often struggle to find specific answers. They might not know the right terminology, or the answer might be scattered across multiple pages.

A documentation chatbot solves this by:

• Understanding natural language questions ("how do I authenticate?" instead of searching for "OAuth bearer token")
• Finding answers across your entire documentation
• Providing instant responses without manual support
• Learning from your actual documentation content, not generic knowledge

Ask AI Button is built specifically for this use case - it's a chatbot that uses only your technical documentation as its knowledge source, ensuring accurate, relevant answers for your users.

This tutorial shows you how to add Ask AI Button to your Docusaurus site.

What You'll Build

By the end of this tutorial, you'll have a fully functional AI chatbot on your Docusaurus site that:

• Answers user questions based on your documentation content
• Appears as a chat widget on every page
• Maintains context about your specific technical documentation

Prerequisites

Before we start, make sure you have:

• A Docusaurus site (v2.0 or higher)
• Access to modify your site's configuration
• An Ask AI Button account with a project ID

Step 1: Add the Script

First, we need to load the Ask AI Button script. Open your docusaurus.config.js and add it to the scripts array:

module.exports = {
  // ... your existing config
  scripts: [
    {
      src: 'https://cdn.ask-ai-button.io/loader-v1.js',
      defer: true,
    },
  ],
};

The defer attribute ensures the script loads after the page content, preventing any performance issues.

Step 2: Configure the Chatbot

Next, we need to tell Ask AI Button about your project. Create a new file at src/theme/Root.js:

import React from 'react';

export default function Root({children}) {
  React.useEffect(() => {
    window.aaib = {
      projectId: 'YOUR_PROJECT_ID', // Replace with your actual ID
    };
  }, []);

  return <>{children}</>;
}

This component wraps your entire Docusaurus app and configures Ask AI Button when the site loads.

Step 3: Handle Static Site Generation

Docusaurus generates static HTML, so we need to ensure our script works during both build time and runtime. Update your Root component to check for the browser environment:

import React from 'react';
import BrowserOnly from '@docusaurus/BrowserOnly';

export default function Root({children}) {
  return (
    <>
      <BrowserOnly>
        {() => {
          window.aaib = {
            projectId: 'YOUR_PROJECT_ID',
          };
          return null;
        }}
      </BrowserOnly>
      {children}
    </>
  );
}

Step 4: Advanced Configuration (Optional)

Ask AI Button supports additional configuration options. Here's a more complete setup:

window.aaib = {
  projectId: 'YOUR_PROJECT_ID',
  theme: 'light', // or 'dark', 'auto'
  position: 'bottom-right', // chatbot position
  primaryColor: '#7c3aed', // match your brand colors
  greeting: 'How can I help you navigate our docs?',
  placeholder: 'Ask about our API, installation, or guides...',
};

For a complete list of configuration parameters, check our configuration documentation.

Step 5: Test Your Integration

After deploying your changes:

1. Visit your Docusaurus site
2. Look for the chat widget (typically bottom-right corner)
3. Ask a question about your documentation
4. Verify the chatbot responds with information from your docs

Troubleshooting Common Issues

Chatbot not appearing:

• Check the browser console for errors
• Verify your project ID is correct
• Ensure the script URL is accessible

Chatbot not finding content:

• Make sure your documentation is indexed by Ask AI Button
• Check your project dashboard for indexing status
• Verify your documentation URLs are accessible

Build errors:

• Use BrowserOnly wrapper for client-side code
• Ensure you're not accessing window during SSR

Customizing for Your Use Case

Different documentation sites have different needs. Here are some customization ideas:

For API documentation:

window.aaib = {
  projectId: 'YOUR_PROJECT_ID',
  greeting: 'Ask me about endpoints, parameters, or authentication',
  suggestedQuestions: [
    'How do I authenticate?',
    'What are the rate limits?',
    'Show me an example API call'
  ],
};

For SDK documentation:

window.aaib = {
  projectId: 'YOUR_PROJECT_ID',
  greeting: 'Need help with our SDK?',
  suggestedQuestions: [
    'How do I install the SDK?',
    'Show me a quick start example',
    'What are the system requirements?'
  ],
};

Performance Considerations

The Ask AI Button script is lightweight and loads asynchronously, but here are some tips to ensure optimal performance:

1. Use the defer attribute on the script tag
2. Load the configuration only in the browser environment
3. Consider lazy-loading the chatbot on user interaction if you have strict performance requirements

Conclusion

Adding an AI chatbot to your Docusaurus documentation takes just a few minutes but can significantly improve how users find information. The chatbot uses your existing documentation as its knowledge base, so it stays up-to-date automatically as you update your docs.

For more detailed integration instructions and troubleshooting, visit our Docusaurus integration guide.

Remember to monitor how users interact with the chatbot through your Ask AI Button dashboard - their questions can reveal gaps in your documentation and help you improve it over time.

Next Steps

• Customize the chatbot appearance to match your brand
• Review chatbot conversations to understand common user questions
• Use insights to improve your documentation structure
• Experiment with suggested questions to guide users

---

Ask AI Button is a chatbot specifically designed for technical documentation. It helps users find answers using only your documentation as the source of truth.