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 template overrides. Works with any MkDocs theme, including Material for MkDocs.

Prerequisites​

Add the chatbot widget​

The <biel-button> component adds a floating chat button to your site.

Chatbot widget for docs

  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. To disable them:

  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​