Skip to main content

Ask AI assistant widget for MkDocs

Add a Biel.ai AI assistant 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 assistant widget​

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

Assistant 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 assistant

    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.

The plugin loads the widget's JavaScript and CSS from the CDN using latest by default. You do not need to install an npm widget package. To use a specific release, set version in mkdocs.yml:

plugins:
  - biel:
      project: <YOUR_PROJECT_ID>
      version: '0.1.93'

Replace 0.1.93 with your chosen release and rebuild your site. Use version: latest to follow new releases again. See CDN version selection for how caching affects latest.

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

Install and configure the plugin to load the assets:

pip install mkdocs-biel

In mkdocs.yml, append Biel to your existing plugins:

plugins:
  - search
  - biel:
      project: <YOUR_PROJECT_ID>
      header_title: Documentation AI

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​