Skip to main content

Ask AI assistant widget for Starlight

Add an AI assistant or AI search widget to your Starlight documentation using the starlight-biel plugin. You can also connect AI agents through MCP, with or without installing the widget.

Prerequisites​

  • A Biel.ai account.
  • A project with indexed content.
  • A Starlight site (Starlight 0.32 or later).
  • Node.js installed.

Add the assistant widget​

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

Assistant widget for docs

  1. Install the plugin:

    npm install starlight-biel

  2. Add the plugin to your Starlight configuration in astro.config.mjs:

    import { defineConfig } from 'astro/config'
    import starlight from '@astrojs/starlight'
    import starlightBiel from 'starlight-biel'

    export default defineConfig({
      integrations: [
        starlight({
          title: 'My Docs',
          plugins: [
            starlightBiel({
              project: '<YOUR_PROJECT_ID>',
              headerTitle: 'Biel.ai assistant',
            }),
          ],
        }),
      ],
    })

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

  3. Run npm run dev and verify the chat button appears in the bottom-right corner.

Customization​

Pass layout options to the plugin as camelCase properties:

starlightBiel({
  project: '<YOUR_PROJECT_ID>',
  bielButtonText: 'Ask AI',
  buttonPosition: 'bottom-right',
  modalPosition: 'bottom-right',
  buttonStyle: 'dark',
  headerTitle: 'Documentation AI',
})

Set enable: false to turn the widget off without removing the configuration.

Add the search widget​

The search widget replaces Starlight's built-in Pagefind search with Biel.ai's AI-powered search. Configure starlight-biel, then override the search component.

Biel search

Install the plugin before adding the override:

npm install starlight-biel

  1. Create src/components/Search.astro with the following content:

    ---
    ---
    <biel-search-button project="<YOUR_PROJECT_ID>" button-style="rounded" header-title="Documentation AI">
      Search
    </biel-search-button>

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

  2. Register the override in your Starlight configuration in astro.config.mjs:

    import starlightBiel from 'starlight-biel'

    starlight({
      components: {
        Search: './src/components/Search.astro',
      },
      plugins: [
        starlightBiel({ project: '<YOUR_PROJECT_ID>' }),
      ],
    })

  3. Run npm run dev and verify the search widget appears in the navbar where Pagefind's search was.

Keeping Pagefind?

Skip the override and the two searches coexist: Pagefind stays in the navbar for keyword lookup and Biel.ai answers questions from the chat button.

Alternative: component overrides​

If you prefer not to use the plugin, or need to place the button inside a custom component, you can add the widget manually with Starlight's head configuration and a footer override.

  1. Load the dependencies in your Astro configuration file (astro.config.mjs):

    import starlight from '@astrojs/starlight'
    import { defineConfig } from 'astro/config'

    export default defineConfig({
      integrations: [
        starlight({
          head: [
            {
              tag: 'link',
              attrs: {
                rel: 'stylesheet',
                href: 'https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.css',
              },
            },
            {
              tag: 'script',
              attrs: {
                type: 'module',
                src: 'https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.esm.js',
              },
            },
          ],
          (...)
        }),
      ],
    })

  2. Create src/components/CustomFooter.astro containing a <biel-button> element alongside the default footer content:

    ---
    import type { Props } from '@astrojs/starlight/props';

    import EditLink from 'virtual:starlight/components/EditLink';
    import Icon from 'virtual:starlight/components/Icon';
    import LastUpdated from 'virtual:starlight/components/LastUpdated';
    import Pagination from 'virtual:starlight/components/Pagination';
    import config from 'virtual:starlight/user-config';
    ---

    <footer class="sl-flex">
        <biel-button project="<YOUR_PROJECT_ID>"
            header-title="Biel.ai assistant"
            button-position="bottom-right"
            modal-position="bottom-right"
            button-style="dark">
                Ask AI
        </biel-button>

        <div class="meta sl-flex">
            <EditLink {...Astro.props} />
            <LastUpdated {...Astro.props} />
        </div>
        <Pagination {...Astro.props} />

        {
            config.credits && (
                <a class="kudos sl-flex" href="https://starlight.astro.build">
                    <Icon name={'starlight'} /> {Astro.locals.t('builtWithStarlight.label')}
                </a>
            )
        }
    </footer>

    <style is:global>
        .right-sidebar-container{
            z-index: -1;
        }
    </style>

    <style>
        footer {
            flex-direction: column;
            gap: 1.5rem;
        }
        .meta {
            gap: 0.75rem 3rem;
            justify-content: space-between;
            flex-wrap: wrap;
            font-size: var(--sl-text-sm);
            color: var(--sl-color-gray-3);
        }
        .meta > :global(p:only-child) {
            margin-inline-start: auto;
        }

        .kudos {
            align-items: center;
            gap: 0.5em;
            margin: 1.5rem auto;
            font-size: var(--sl-text-xs);
            text-decoration: none;
            color: var(--sl-color-gray-3);
        }
        .kudos :global(svg) {
            color: var(--sl-color-orange);
        }
        .kudos:hover {
            color: var(--sl-color-white);
        }
    </style>

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

    The global style sets z-index: -1 on .right-sidebar-container to ensure the button is placed on top of the right sidebar.

  3. Register the footer override in astro.config.mjs:

    import starlight from '@astrojs/starlight'
    import { defineConfig } from 'astro/config'

    export default defineConfig({
      integrations: [
        starlight({
          (...)
          components: {
            Footer: './src/components/CustomFooter.astro',
          },
          (...)
        }),
      ],
    })

  4. Run npm run dev and verify the chat button appears in the bottom-right corner.

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​