Skip to main content

Ask AI assistant widget for Zensical

Add a Biel.ai AI assistant or AI search widget to your Zensical site using template overrides. You can also connect AI agents through MCP, with or without installing the widget.

Prerequisites​

Add the assistant widget​

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

Assistant widget for docs

  1. Create a custom template directory:

    mkdir -p overrides

  2. Create 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 Zensical at the overrides directory.

    In zensical.toml:

    [project.theme]
    custom_dir = "overrides"

    If your project still uses the legacy mkdocs.yml, the equivalent is:

    theme:
      custom_dir: overrides

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

Disable conflicting keyboard shortcuts​

Like Material for MkDocs, Zensical registers keyboard shortcuts (f, s, / for search and 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. Register the script.

    In zensical.toml:

    [project]
    extra_javascript = ["javascripts/disable-search-autofocus.js"]

    Or in mkdocs.yml:

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

Add the search widget​

  1. Create overrides/main.html to load the widget assets. If this file already exists, merge the extrahead block and keep your other blocks:

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

  2. Create overrides/partials/search.html to replace the built-in search control:

    <biel-search-button project="<YOUR_PROJECT_ID>" button-style="rounded">
        Search
    </biel-search-button>

    Replace <YOUR_PROJECT_ID> with your project ID.

  3. Point Zensical at the overrides directory in zensical.toml:

    [project.theme]
    custom_dir = "overrides"

    For mkdocs.yml, set theme.custom_dir to overrides.

  4. Run zensical serve. Open Search, enter a term from your documentation, and open a result. Apply the keyboard shortcut configuration.

Connect AI agents with MCP​

Let AI tools search and read your indexed documentation. MCP is available on every plan and during your trial.

  1. In the Biel.ai dashboard, open your project’s Settings > MCP.
  2. Select Enable MCP server and click Save.
  3. In the widget, open Connect via MCP using the <> button. Select your AI client or choose MCP URL to copy the endpoint into its settings.

Without the widget: after enabling MCP, copy MCP endpoint from Settings > MCP and add it to your AI client. No widget installation or website changes are required.

The widget also exposes WebMCP tools to compatible browser agents visiting your site. Use the latest widget release and keep Enable WebMCP selected in Settings > MCP.

Next steps​