Ask AI assistant widget for Docusaurus

Add a Biel.ai AI assistant or AI search widget to your Docusaurus v3 site using the docusaurus-biel plugin.

Prerequisites

A Biel.ai account.
A project with indexed content.
A Docusaurus v3 site.
Node.js installed.

The docusaurus-biel plugin adds a floating chat button to your site.

Install the plugin:
```
npm install docusaurus-biel
```

Add the plugin to docusaurus.config.js:

plugins: [
    [
        'docusaurus-biel',{
            project: '<YOUR_PROJECT_ID>',
            headerTitle: 'Biel.ai assistant',
            version: 'latest'
        }
    ]
],

Replace <YOUR_PROJECT_ID> with your project's ID from the Biel.ai dashboard.

Run npm start and verify the assistant appears on your site.

The plugin loads the widget's JavaScript and CSS from the CDN using latest by default. You do not need to install biel-search separately. This follows the latest published widget release, independently of your npm lockfile.

To use a specific release, set version in docusaurus.config.js and rebuild your site:

plugins: [
    ['docusaurus-biel', {
        project: '<YOUR_PROJECT_ID>',
        version: '0.1.93',
    }],
],

Replace 0.1.93 with your chosen release. Use version: 'latest' to follow new releases again. See CDN version selection for how caching affects latest.

Customization

Pass layout options to the plugin as camelCase properties:

plugins: [
    [
        'docusaurus-biel',{
            enable: true,
            project: '<YOUR_PROJECT_ID>',
            bielButtonText: 'ASK AI',
            buttonPosition: 'center-right',
            modalPosition: 'sidebar-right',
            headerTitle: 'Biel.ai assistant',
            buttonStyle: 'dark',
        }
    ]
],

To override the widget's styles (colors, fonts, etc.), add CSS custom properties to your src/css/custom.css file:

:root {
    --biel-primary-color: #FF0000;
}

See Styles for the full list of CSS properties.

Docusaurus not loading your custom CSS?

Make sure custom.css is referenced in docusaurus.config.js under the classic preset:

presets: [
    [
        'classic',
        {
            theme: {
                customCss: require.resolve('./src/css/custom.css'),
            },
        },
    ],
],

The search widget replaces the default Docusaurus search bar with Biel.ai's AI-powered search.

Install the plugin:
```
npm install docusaurus-biel
```

plugins: [
    [
        'docusaurus-biel', {
            project: '<YOUR_PROJECT_ID>',
            headerTitle: 'Documentation AI',
            version: 'latest',
            enable: false,
        },
    ],
],

Replace <YOUR_PROJECT_ID> with your project ID. enable: false hides the floating assistant button while keeping the assets available for search. Set it to true to use both widgets.

Eject the SearchBar component using swizzling:
```
npm run swizzle @docusaurus/theme-classic SearchBar
```
When prompted, choose TypeScript and Eject.

Open src/theme/SearchBar.tsx and replace its content with:

import React from 'react';

export default function SearchBar() {
    const projectId = '<PROJECT_ID>';
    const headerTitle = 'Documentation assistant';
    // @ts-ignore: Not a React component
    return <biel-search-button project={projectId} button-style="rounded" header-title={headerTitle}>Search</biel-search-button>;
}

Replace <PROJECT_ID> with your project's ID from the Biel.ai dashboard.

Run npm start and verify the search widget appears in the navbar.

Using search without the assistant?

Set enable: false in the docusaurus-biel plugin config to hide the floating chat button:

plugins: [
    [
        'docusaurus-biel', {
            enable: false,
            project: '<YOUR_PROJECT_ID>',
            headerTitle: 'Biel.ai assistant',
            version: 'latest'
        }
    ]
],

Multilingual support

If your Docusaurus site uses i18n, you can localize the assistant's UI strings per locale. This approach uses biel-react instead of the docusaurus-biel plugin.

Assistant widget i18n

Install biel-react:
```
npm install biel-react
```
Already using docusaurus-biel?
This setup replaces it. Run npm uninstall docusaurus-biel to remove the plugin.
Wrap the Footer component using swizzling to inject the assistant before the closing body tag:
```
npm run swizzle @docusaurus/theme-classic Footer
```
When prompted, choose Wrap.

Open src/theme/Footer/index.js and replace its content with:

import React, { useEffect } from 'react';
import Footer from '@theme-original/Footer';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import { BielButton } from 'biel-react';
import { defineCustomElements } from 'biel-search/loader';
import 'biel-search/dist/biel-search/biel-search.css';

function BielWidget() {
    const { i18n } = useDocusaurusContext();
    const language = i18n.currentLocale;
    const projectId = '<PROJECT_ID>'; // Replace with your actual project ID

    const placeholders = {
        en: {
            bielButtonText: "Ask AI",
            sendButtonText: 'Send',
            inputPlaceholderText: 'Type your message',
            error403: 'Oops! The request URL does not match the one defined for this project.',
            error404: 'Oops! We could not find the provided project ID.',
            errorDefault: 'Oops! Please try again later.',
            headerTitle: 'Need help?',
            footerText: 'AI generated answers. Always verify the sources before using them.',
            sourcesText: 'Sources',
            suggestedQuestions: JSON.stringify(["What is Biel.ai?", "How to install in Docusaurus?"]),
            suggestedQuestionsTitle: 'Suggested questions',
            termsTitle: 'Assistant Terms & Conditions',
            termsDescription: "Please review our <a href='https://biel.ai/terms' target='_blank' rel='noopener'>Terms & Conditions</a> before proceeding.",
            termsCheckboxText: 'I have read and agree to the Terms & Conditions.',
            welcomeMessage: 'Hello! How can I help you today?'
        },
        es: {
            bielButtonText: "Pregúntame",
            sendButtonText: 'Enviar',
            inputPlaceholderText: 'Escribe tu mensaje',
            error403: '¡Ups! La URL de solicitud no coincide con la definida para este proyecto.',
            error404: '¡Ups! No pudimos encontrar el ID de proyecto proporcionado.',
            errorDefault: '¡Ups! Por favor, intenta de nuevo más tarde.',
            headerTitle: '¿Necesitas ayuda?',
            footerText: 'Respuestas generadas por IA. Verifica siempre las fuentes antes de usarlas.',
            sourcesText: 'Fuentes',
            suggestedQuestions: JSON.stringify(["¿Qué es Biel.ai?", "¿Cómo instalar en Docusaurus?"]),
            suggestedQuestionsTitle: 'Preguntas sugeridas',
            termsTitle: 'Términos y condiciones del asistente',
            termsDescription: "Por favor revisa nuestros <a href='https://biel.ai/terms' target='_blank' rel='noopener'>Términos y Condiciones</a> antes de continuar.",
            termsCheckboxText: 'He leído y acepto los Términos y Condiciones.',
            welcomeMessage: '¡Hola! ¿En qué puedo ayudarte hoy?'
        }
    };

    const {
        bielButtonText,
        error403,
        error404,
        errorDefault,
        footerText,
        headerTitle,
        inputPlaceholderText,
        sendButtonText,
        sourcesText,
        suggestedQuestions,
        suggestedQuestionsTitle,
        termsCheckboxText,
        termsDescription,
        termsTitle,
        welcomeMessage,
    } = placeholders[language] || placeholders.en;

    useEffect(() => {
        if (typeof window !== 'undefined') {
            defineCustomElements(window);
        }
    }, []);

    return (
        <div className="biel-widget">
            <BielButton
                project={projectId}
                button-position="bottom-right"
                button-style="dark"
                modal-position="bottom-right"
                error-message-4-0-3={error403}
                error-message-4-0-4={error404}
                error-message-default={errorDefault}
                footer-text={footerText}
                header-title={headerTitle}
                input-placeholder-text={inputPlaceholderText}
                send-button-text={sendButtonText}
                sources-text={sourcesText}
                suggested-questions={suggestedQuestions}
                suggested-questions-title={suggestedQuestionsTitle}
                terms-checkbox-text={termsCheckboxText}
                terms-description={termsDescription}
                terms-title={termsTitle}
                welcome-message={welcomeMessage}
            >
            {bielButtonText}
            </BielButton>
        </div>
    );
}

export default function FooterWrapper(props) {
    return (
        <>
            <Footer {...props} />
            <BielWidget />
        </>
    );
}

Replace <PROJECT_ID> with your project's ID from the Biel.ai dashboard. Update the placeholders object with your supported languages.

Run npm start and verify the assistant displays localized strings when you switch locales.

Next steps

View the docusaurus-biel source and releases.
Customize the widget's appearance, behavior, and tone.
Connect integrations like GitHub Actions, MCP, or Zapier.

Ask AI assistant widget for Docusaurus

Prerequisites

Add the assistant widget

Select a widget version

Customization

Add the search widget

Multilingual support

Next steps

Prerequisites​

Add the assistant widget​

Select a widget version​

Customization​

Add the search widget​

Multilingual support​

Next steps​

Prerequisites

Add the assistant widget

Select a widget version

Customization

Add the search widget

Multilingual support

Next steps