# Ask AI chatbot widget for Starlight

> For the complete documentation index, see [llms.txt](/llms.txt)

> Add an AI chatbot or AI search widget to your Starlight documentation site with the starlight-biel plugin.

Add an [AI chatbot](https://biel.ai) or [AI search widget](https://biel.ai/ai-search-for-docs) to your Starlight documentation using the `starlight-biel` plugin.

## Prerequisites

- A [Biel.ai account](https://app.biel.ai/accounts/signup/).
- A [project](https://docs.biel.ai/quickstart.md#2-create-a-project) with indexed content.
- A Starlight site (Starlight 0.32 or later).
- Node.js installed.

## Add the chatbot widget

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

![Chatbot widget for docs](./images/biel-widget-docs.png)

1. Install the plugin:

    ```console
    npm install starlight-biel
    ```

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

    ```js

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

    Replace `<YOUR_PROJECT_ID>` with your project's ID from the [Biel.ai dashboard](https://docs.biel.ai/quickstart.md#2-create-a-project).

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

## Customization

Pass [layout options](https://docs.biel.ai/customization/layout.md) to the plugin as camelCase properties:

```js
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. The `starlight-biel` plugin already loads the required assets, so one component override is all it takes.

![Biel search](./images/biel-search-widget.png)

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

    ```astro
    ---
    ---
    <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](https://docs.biel.ai/quickstart.md#2-create-a-project).

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

    ```js
    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.

:::tip 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`):

    ```js

    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:

    ```astro
    ---

    ---

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

        
            <EditLink {...Astro.props} />
            <LastUpdated {...Astro.props} />
        
        <Pagination {...Astro.props} />

        { config.credits && (
                
                    <Icon name={'starlight'} /> {Astro.locals.t('builtWithStarlight.label')}
                
            )}
    </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](https://docs.biel.ai/quickstart.md#2-create-a-project).

    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`:

    ```js

    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.

## Next steps

- [View the `starlight-biel` source and releases](https://github.com/TechDocsStudio/starlight-biel).
- [Customize](https://docs.biel.ai/customization.md) the widget's appearance, behavior, and tone.
- [Connect integrations](https://docs.biel.ai/integrations.md) like GitHub Actions, MCP, or Zapier.