For the complete documentation index, see llms.txt
Skip to main content

Ask AI chatbot widget for MkDocs

Add a Biel.ai AI chatbot or AI search widget to your MkDocs site using the mkdocs-biel plugin. Works with any MkDocs theme, including Material for MkDocs.

Prerequisites​

Add the chatbot widget​

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

Chatbot widget for docs

  1. Install the plugin:

    pip install mkdocs-biel

  2. Add the plugin to mkdocs.yml:

    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.

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

Customization​

Pass layout options to the plugin as snake_case keys:

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

On Material for MkDocs, override the search partial:

  1. Create overrides/partials/search.html 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. Point mkdocs.yml at the overrides directory:

    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.

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:

    mkdir -p docs/overrides

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

    {% 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.

  3. Point mkdocs.yml to the overrides directory:

    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:

    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:

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

Next steps​