How to Add Asyntai AI Chatbot to Docusaurus

Step-by-step guide for Docusaurus documentation sites

Platform:

Step 1: Get Your Embed Code

First, go to your Asyntai Dashboard and scroll down to the "Embed Code" section. Copy your unique embed code which will look like this:

<script async src="https://asyntai.com/static/js/chat-widget.js" data-asyntai-id="YOUR_WIDGET_ID"></script>

Note: The code above is just an example. You must copy your own unique embed code from your Dashboard as it contains your personal widget ID.

Step 2: Add Script to docusaurus.config.js (Recommended)

The best way to add the chatbot to all pages of your Docusaurus site is through the configuration file:

Open your Docusaurus project in your code editor
Locate and open the docusaurus.config.js file in your project root
Find the const config = { } object
Add or update the scripts field with your Asyntai widget:

const config = {
  // ... other config options

  scripts: [
    // Other scripts if any
    {
      src: 'https://asyntai.com/static/js/chat-widget.js',
      'data-asyntai-id': 'YOUR_WIDGET_ID',
      async: true,
    },
  ],

  // ... rest of config
};

Save the docusaurus.config.js file
Rebuild your site by running npm run build or yarn build
Restart the development server if running locally

Tip: The scripts field accepts an array of JavaScript sources. The script tag will be inserted in the HTML head of every page automatically. This is the cleanest and most maintainable method for Docusaurus sites.

Alternative Method 1: String Format (Simpler Syntax)

If you prefer a simpler approach, you can use string format in the scripts array:

const config = {
  scripts: [
    'https://asyntai.com/static/js/chat-widget.js',
  ],
};

Note: When using string format, you'll need to modify the script URL to include your widget ID as a query parameter, or use the object format shown in Step 2 which allows you to set the data-asyntai-id attribute directly.

Alternative Method 2: Custom Head Tags

You can also add the script using the headTags field in docusaurus.config.js:

const config = {
  headTags: [
    {
      tagName: 'script',
      attributes: {
        src: 'https://asyntai.com/static/js/chat-widget.js',
        'data-asyntai-id': 'YOUR_WIDGET_ID',
        async: true,
      },
    },
  ],
};

Tip: The headTags field provides more control over the exact HTML tags inserted into the <head> section. This method is functionally equivalent to using the scripts field.

Alternative Method 3: Custom HTML Template (Advanced)

For advanced users who need complete control over the HTML template:

Create a new directory: src/theme (if it doesn't exist)
Create a file: src/theme/Root.js
Add the following code to inject the script dynamically:

import React, { useEffect } from 'react';

export default function Root({children}) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://asyntai.com/static/js/chat-widget.js';
    script.setAttribute('data-asyntai-id', 'YOUR_WIDGET_ID');
    script.async = true;
    document.head.appendChild(script);

    return () => {
      // Cleanup when component unmounts
      document.head.removeChild(script);
    };
  }, []);

  return <>{children}</>;
}

Save the file and rebuild your site

Important: The Root.js component wraps your entire application. This advanced method should only be used if you need custom JavaScript logic or have specific requirements that can't be met with the configuration file approach.

Alternative Method 4: Swizzle Footer Component

You can customize the footer to include the script:

Run the swizzle command: npm run swizzle @docusaurus/theme-classic Footer -- --eject
This creates a copy of the Footer component in src/theme/Footer/
Edit the Footer component to include your script tag
Add the script before the closing tag of the footer
Save and rebuild your site

Note: Swizzling gives you full control over Docusaurus components, but it means you'll need to maintain that component yourself. Updates to Docusaurus won't automatically update swizzled components.

Step 3: Build and Deploy

After adding the code, build and deploy your Docusaurus site:

# Build the site
npm run build

# Or with Yarn
yarn build

# Deploy to your hosting platform
# (Vercel, Netlify, GitHub Pages, etc.)

Tip: During development, run npm start or yarn start to preview your changes locally. The chatbot should appear in the bottom right corner on all pages.

Step 4: Verify Installation

After deploying your changes, open your documentation site in a new browser tab. You should see the chat widget button in the bottom right corner. Click it to ensure it opens and functions correctly.

Not seeing the widget? Make sure you've rebuilt your site after making changes. Check that you replaced YOUR_WIDGET_ID with your actual widget ID from the dashboard. Clear your browser cache or view in incognito mode. Open the browser console (F12) to check for any JavaScript errors.

Documentation