Docusaurus Integration

Enhance your Docusaurus documentation with Ask0's AI search and chat. Simple integration for Docusaurus v2 and v3 sites.

Integrate Ask0 AI assistant into your Docusaurus documentation to help users find answers quickly.

Quick Setup

Get Your Project ID

Add to Docusaurus Config

Add Ask0 script in docusaurus.config.js:

docusaurus.config.js

module.exports = {
  // ... other config

  scripts: [
    {
      src: 'https://assets.ask0.ai/scripts/ask.js',
      async: true,
      'data-project-id': 'YOUR_PROJECT_ID',
      'data-position': 'bottom-right',
      'data-theme': 'auto',
    },
  ],

  // ... rest of config
};

Verify Installation

Start your Docusaurus site and look for the Ask0 widget in the bottom-right corner.

npm run start

Advanced Configuration

Custom React Component

Create a custom component for more control:

src/components/Ask0Widget.js

import React, { useEffect } from 'react';
import { useColorMode } from '@docusaurus/theme-common';
import BrowserOnly from '@docusaurus/BrowserOnly';

export default function Ask0Widget() {
  return (
    <BrowserOnly>
      {() => {
        const { colorMode } = useColorMode();

        useEffect(() => {
          // Load Ask0 script
          const script = document.createElement('script');
          script.src = 'https://assets.ask0.ai/scripts/ask.js';
          script.async = true;
          script.dataset.projectId = 'YOUR_PROJECT_ID';
          script.dataset.theme = colorMode;

          document.body.appendChild(script);

          // Update theme when it changes
          const handleThemeChange = () => {
            if (window.ask0) {
              window.ask0.setTheme(colorMode);
            }
          };

          return () => {
            document.body.removeChild(script);
            if (window.ask0) {
              window.ask0.destroy();
            }
          };
        }, [colorMode]);

        return null;
      }}
    </BrowserOnly>
  );
}

Add to your theme:

import React from 'react';
import Ask0Widget from '@site/src/components/Ask0Widget';

export default function Root({ children }) {
  return (
    <>
      {children}
      <Ask0Widget />
    </>
  );
}

Theme Integration

Sync with Docusaurus themes:

src/theme/Ask0Integration.js

import { useColorMode } from '@docusaurus/theme-common';
import { useEffect } from 'react';

export function useAsk0Theme() {
  const { colorMode } = useColorMode();

  useEffect(() => {
    // Wait for Ask0 to load
    const checkAsk0 = setInterval(() => {
      if (window.ask0) {
        clearInterval(checkAsk0);

        // Set theme
        window.ask0.setTheme(colorMode);

        // Get Docusaurus colors
        const styles = getComputedStyle(document.documentElement);
        const primaryColor = styles.getPropertyValue('--ifm-color-primary');

        window.ask0.setColors({
          primary: primaryColor,
        });
      }
    }, 100);

    return () => clearInterval(checkAsk0);
  }, [colorMode]);
}

Search Bar Replacement

Replace or augment Docusaurus search:

src/theme/SearchBar/index.js

import React from 'react';
import { translate } from '@docusaurus/Translate';

export default function SearchBar() {
  const handleClick = () => {
    if (window.ask0) {
      window.ask0.open();
    }
  };

  return (
    <button
      className="navbar__search"
      onClick={handleClick}
      aria-label={translate({
        id: 'theme.SearchBar.label',
        message: 'Search',
        description: 'The ARIA label for the search button',
      })}
    >
      <span>Ask AI</span>
      <kbd className="navbar__search-key">⌘K</kbd>
    </button>
  );
}

Plugin Configuration

Create Ask0 Plugin

Create a custom Docusaurus plugin:

src/plugins/ask0-plugin.js

module.exports = function (context, options) {
  return {
    name: 'docusaurus-plugin-ask0',

    injectHtmlTags({ content }) {
      return {
        postBodyTags: [
          {
            tagName: 'script',
            attributes: {
              src: 'https://assets.ask0.ai/scripts/ask.js',
              async: true,
              'data-project-id': options.projectId,
              'data-position': options.position || 'bottom-right',
              'data-theme': options.theme || 'auto',
              'data-greeting': options.greeting,
            },
          },
        ],
      };
    },

    getClientModules() {
      return [];
    },
  };
};

Use in config:

docusaurus.config.js

module.exports = {
  plugins: [
    [
      './src/plugins/ask0-plugin',
      {
        projectId: 'YOUR_PROJECT_ID',
        position: 'bottom-right',
        theme: 'auto',
        greeting: 'Need help with the docs?',
      },
    ],
  ],
};

Versioned Docs

Handle versioned documentation:

// Configure Ask0 to index versioned docs
const ask0Config = {
  sources: [
    {
      url: 'https://docs.site.com/docs/next',
      label: 'Next (Unreleased)',
    },
    {
      url: 'https://docs.site.com/docs',
      label: 'Current',
    },
    {
      url: 'https://docs.site.com/docs/1.0.0',
      label: 'v1.0.0',
    },
  ],
};

i18n Support

Support internationalization:

import { useLocation } from '@docusaurus/router';

export function Ask0I18n() {
  const location = useLocation();
  const locale = location.pathname.split('/')[1];

  useEffect(() => {
    if (window.ask0) {
      // Set language based on locale
      const languageMap = {
        'en': 'en',
        'es': 'es',
        'fr': 'fr',
        'de': 'de',
        'zh-CN': 'zh',
      };

      window.ask0.setLanguage(languageMap[locale] || 'en');
    }
  }, [locale]);

  return null;
}

MDX Components

Add Ask0 triggers in MDX:

docs/example.mdx

import AskButton from '@site/src/components/AskButton';


Having trouble? <AskButton question="How do I get started?" />

## Installation

<AskButton>
  Ask AI about installation
</AskButton>

Component implementation:

src/components/AskButton.js

export default function AskButton({ children, question }) {
  const handleClick = () => {
    if (window.ask0) {
      window.ask0.open();
      if (question) {
        window.ask0.ask(question);
      }
    }
  };

  return (
    <button onClick={handleClick} className="ask-button">
      {children || 'Ask AI'}
    </button>
  );
}

Analytics Integration

Track documentation usage:

// Track Ask0 events in Docusaurus
window.ask0.on('message', (event) => {
  // Send to Google Analytics
  if (typeof gtag !== 'undefined') {
    gtag('event', 'ask0_question', {
      question: event.message,
      page: window.location.pathname,
    });
  }
});

Swizzling Components

Customize via swizzling:

npm run swizzle @docusaurus/theme-classic Footer -- --wrap

Add Ask0 to footer:

src/theme/Footer/index.js

import React from 'react';
import Footer from '@theme-original/Footer';

export default function FooterWrapper(props) {
  return (
    <>
      <Footer {...props} />
      <div className="ask0-footer-trigger">
        <button onClick={() => window.ask0?.toggle()}>
          💬 Ask AI Assistant
        </button>
      </div>
    </>
  );
}

Environment Variables

Configure with environment variables:

.env

REACT_APP_ASK0_PROJECT_ID=your_project_id
REACT_APP_ASK0_POSITION=bottom-right
REACT_APP_ASK0_THEME=auto

Use in config:

scripts: [
  {
    src: 'https://assets.ask0.ai/scripts/ask.js',
    'data-project-id': process.env.REACT_APP_ASK0_PROJECT_ID,
  },
],

Styling

Match Docusaurus design:

src/css/custom.css

/* Ask0 customization for Docusaurus */
:root {
  --ask0-primary: var(--ifm-color-primary);
  --ask0-font-family: var(--ifm-font-family-base);
  --ask0-radius: var(--ifm-global-radius);
}

/* Light theme */
[data-theme='light'] .ask0-widget {
  --ask0-background: var(--ifm-background-color);
  --ask0-foreground: var(--ifm-font-color-base);
}

/* Dark theme */
[data-theme='dark'] .ask0-widget {
  --ask0-background: var(--ifm-background-color);
  --ask0-foreground: var(--ifm-font-color-base);
}

/* Custom trigger button */
.ask0-trigger {
  position: fixed;
  bottom: 2rem;
  right: 2rem;
  z-index: 999;
  padding: 0.75rem 1.5rem;
  background: var(--ifm-color-primary);
  color: white;
  border-radius: 9999px;
  box-shadow: var(--ifm-global-shadow-md);
  cursor: pointer;
  transition: all 0.3s;
}

.ask0-trigger:hover {
  transform: scale(1.05);
  box-shadow: var(--ifm-global-shadow-lg);
}