Skip to main content

Ask AI chatbot widget for Sphinx

Add a Biel.ai AI chatbot or AI search widget to your Sphinx documentation using the sphinx-biel package. Works with any Sphinx theme, including Read the Docs.

Prerequisites​

Add the chatbot widget​

The sphinx-biel extension adds a floating chat button to your site.

Chatbot widget for docs

  1. Install the package:

    pip install sphinx-biel

  2. Add the extension to your conf.py:

    extensions = ['sphinx_biel']

  3. Configure your project ID in conf.py:

    biel_project = '<YOUR_PROJECT_ID>'
    biel_header_title = 'Biel.ai chatbot'
    biel_version = 'latest'

    Replace <YOUR_PROJECT_ID> with your project's ID from the Biel.ai dashboard.

  4. Build and verify:

    make html

    Open the built documentation in a browser and verify the chatbot appears.

Add the search widget​

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

Biel search

  1. Create _templates/searchbox.html in your project 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. Make sure conf.py points at your templates directory:

    templates_path = ["_templates"]

  3. Rebuild and verify the search widget appears where the theme's search box was (the sidebar on the Read the Docs theme).

Customization​

Pass layout options in conf.py with these naming conventions:

  • Prefix each option with biel_ (e.g., project → biel_project).
  • Replace hyphens with underscores (e.g., button-position → biel_button_position).
biel_button_style = "light"
biel_button_position = "center-right"

Next steps​