# Ask AI chatbot widget for MkDocs

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

> Add an AI chatbot or AI search widget to your MkDocs site with Biel.ai.

Add a Biel.ai [AI chatbot](https://biel.ai) or [AI search widget](https://biel.ai/ai-search-for-docs) to your MkDocs site using the `mkdocs-biel` plugin. Works with any MkDocs theme, including Material for MkDocs.

## 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 MkDocs site.

## Add the chatbot widget

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

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

1. Install the plugin:

    ```console
    pip install mkdocs-biel
    ```

2. Add the plugin to `mkdocs.yml`:

    ```yaml
    plugins:
      - search
      - biel:
          project: <YOUR_PROJECT_ID>
          header_title: 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 `mkdocs serve` 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 snake_case keys:

```yaml
plugins:
  - biel:
      project: <YOUR_PROJECT_ID>
      button_text: Ask AI
      button_position: bottom-right
      modal_position: bottom-right
      button_style: dark
      header_title: Documentation AI
```

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

## Add the search widget

The search widget replaces the theme's search with Biel.ai's AI-powered search. The `mkdocs-biel` plugin already loads the required assets, so overriding one template is all it takes.

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

On **Material for MkDocs**, override the search partial:

1. Create `overrides/partials/search.html` with the following content:

    ```html
    <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. Point `mkdocs.yml` at the overrides directory:

    ```yaml
    theme:
      name: material
      custom_dir: overrides
    ```

3. Run `mkdocs serve` and verify the search widget appears in the header where Material's search was.

On other themes, place the same `<biel-search-button>` element in any template override that renders in your header or sidebar.

:::tip Keeping the built-in search?
Skip the override and the two searches coexist: the theme's keyword search stays in the header and Biel.ai answers questions from the chat button.
:::

## Alternative: template overrides

If you prefer not to use the plugin, you can add the widget with template overrides instead.

1. Create a custom template directory:

    ```console
    mkdir -p docs/overrides
    ```

2. Create `docs/overrides/main.html` with the following content:

    ```html
    {% extends "base.html" %}

    {% block extrahead %}
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.css">
    <script type="module" src="https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.esm.js"></script>
    {% endblock %}

    {% block content %}
    {{ super() }}

    <biel-button project="<YOUR_PROJECT_ID>" header-title="Documentation AI" button-position="bottom-right" modal-position="bottom-right" button-style="dark">
            Ask AI
    </biel-button>
    {% endblock %}
    ```

    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. Point `mkdocs.yml` to the overrides directory:

    ```yaml
    theme:
      name: material  # or your preferred theme
      custom_dir: 'docs/overrides'
    ```

4. Run `mkdocs serve` and verify the chat button appears in the bottom-right corner.

## Material for MkDocs keyboard shortcuts

Material for MkDocs registers keyboard shortcuts (`f`, `s`, `/` for search; `p`, `n` for navigation) that can conflict with Biel.ai's input handling.

**Using the `mkdocs-biel` plugin?** The plugin fixes this automatically: keystrokes inside the widget are scoped to it, and Material's shortcuts keep working everywhere else on the page. Set `theme_shortcuts_fix: false` in the plugin options to opt out.

**Using template overrides?** Disable the shortcuts manually:

1. Create `docs/javascripts/disable-search-autofocus.js`:

    ```javascript
    document.addEventListener('keydown', (e) => { const blockedKeys = ['f', 's', '/', 'p', 'n', ',', '.'];
      if (blockedKeys.includes(e.key.toLowerCase())) { e.stopPropagation();}});
    ```

2. Add the script to `mkdocs.yml`:

    ```yaml
    extra_javascript:
      - javascripts/disable-search-autofocus.js
    ```

## Next steps

- [View the `mkdocs-biel` source and releases](https://github.com/TechDocsStudio/mkdocs-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.