Skip to main content

Ask AI assistant widget for Nextra

Add a Biel.ai AI assistant or AI search widget to your Nextra documentation using the biel-react package. You can also connect AI agents through MCP, with or without installing the widget.

Info

This guide covers Nextra v2 (Pages Router). If your project uses Nextra v3 (App Router with app/layout.tsx), see the Next.js installation guide instead.

Prerequisites​

Add the assistant widget​

The BielButton React component adds a floating chat button to your site.

Assistant widget for docs

  1. Install the package:

    npm install biel-react biel-search

  2. Create or update pages/_app.tsx:

    import type { AppProps } from 'next/app';
    import { useEffect } from 'react';
    import { BielButton } from 'biel-react';
    import bielPackage from 'biel-search/package.json';
    import 'biel-search/dist/biel-search/biel-search.css';

    export default function App({ Component, pageProps }: AppProps) {
      useEffect(() => {
        if (typeof window !== 'undefined') {
          if (!document.querySelector('script[data-biel]')) {
            const script = document.createElement('script');
            script.type = 'module';
            script.src = `https://cdn.jsdelivr.net/npm/biel-search@${bielPackage.version}/dist/biel-search/biel-search.esm.js`;
            script.dataset.biel = '';
            document.head.appendChild(script);
          }
        }
      }, []);

      return (
        <>
          <Component {...pageProps} />
          <BielButton
            project="<YOUR_PROJECT_ID>"
            header-title="Biel.ai assistant"
            button-position="bottom-right"
            modal-position="bottom-right"
            button-style="dark"
          >
            Ask AI
          </BielButton>
        </>
      );
    }

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

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

Add the search widget​

For Nextra v2, replace the docs theme’s search component with Biel.ai:

  1. Install biel-react:

    npm install biel-react biel-search

  2. Create components/BielSearch.tsx:

    import { useEffect } from 'react';
    import { BielSearchButton } from 'biel-react';
    import bielPackage from 'biel-search/package.json';

    export default function BielSearch() {
      useEffect(() => {
        if (!document.querySelector('script[data-biel]')) {
          const script = document.createElement('script');
          script.type = 'module';
          script.src = `https://cdn.jsdelivr.net/npm/biel-search@${bielPackage.version}/dist/biel-search/biel-search.esm.js`;
          script.dataset.biel = '';
          document.head.appendChild(script);
        }
      }, []);

      return (
        <BielSearchButton project="<YOUR_PROJECT_ID>" button-style="rounded">
          Search
        </BielSearchButton>
      );
    }

    Replace <YOUR_PROJECT_ID> with your project ID.

  3. Import the widget stylesheet in pages/_app.tsx:

    import 'biel-search/dist/biel-search/biel-search.css';

  4. In theme.config.tsx, import the component and set search.component. Keep your existing theme options:

    import BielSearch from './components/BielSearch';

    export default {
      // Your existing theme options.
      search: { component: <BielSearch /> },
    };

  5. Run npm run dev. Open Search, enter a documentation term, and open a result.

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.

Next steps​