Skip to main content

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. You can also connect AI agents through MCP, with or without installing the widget.

Prerequisites​

Add the assistant widget​

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

Assistant widget for docs

  1. Install the plugin:

    npm install docusaurus-biel

  2. 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.

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

Select a widget version​

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 a published biel-search version on npm. 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'),
            },
        },
    ],
],

Add the search widget​

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

Biel search

  1. Install the plugin:

    npm install docusaurus-biel

  2. Register the plugin in docusaurus.config.js to load the widget assets:

    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.

  3. Eject the SearchBar component using swizzling:

    npm run swizzle @docusaurus/theme-classic SearchBar

    When prompted, choose TypeScript and Eject.

  4. 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.

  5. 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'
        }
    ]
],

Connect AI agents with MCP​

Let AI tools search and read your indexed documentation. MCP is available on every plan and during your trial.

  1. In the Biel.ai dashboard, open your project’s Settings > MCP.
  2. Select Enable MCP server and click Save.
  3. In the widget, open Connect via MCP using the <> button. Select your AI client or choose MCP URL to copy the endpoint into its settings.

Without the widget: after enabling MCP, copy MCP endpoint from Settings > MCP and add it to your AI client. No widget installation or website changes are required.

The widget also exposes WebMCP tools to compatible browser agents visiting your site. Use the latest widget release and keep Enable WebMCP selected in Settings > MCP.

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

  1. Install biel-react:

    npm install biel-react
    Already using docusaurus-biel?

    This setup replaces it. Run npm uninstall docusaurus-biel to remove the plugin.

  2. 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.

  3. 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.

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

Next steps​