Skip to content

Add Kapa AI search

This page provides some quick guidance on adding Kapa to your Material for MkDocs documentation site.

Kapa: what and why

Kapa provides a RAG chatbot. From their site:

Kapa.ai turns your technical content into a production-ready Al assistant you can deploy on your documentation in days.

You add a chatbot to your site that's focused on your content. The answers use the sources that you've chosen to connect. This makes them more likely to be accurate and up to date compared to a generic AI.

Kapa can pull in a wide range of data sources in addition to your documentation site, and you can add the chatbot to places like your company Slack or Discord, not just your docs. It also provides some very useful analytics and feedback from users, which can help identify documentation gaps (this is one of my favourite features). Kapa is constantly adding new features and functionality, so check out their website and docs for full details.

At the moment (May 31, 2025), Kapa does the initial setup for all users, and doesn't have a completely self-serve option. They generously gave me a free trial to play around with it. I'm hoping they'll eventually offer self-serve, as it felt fairly straightfoward to set up myself.

Adding Kapa as a simple widget

By default, Kapa provides a widget in the bottom right of your site. If you want to use this, then you can work through the Kapa docs.

  1. Connect Data Sources: connect your documentation site, and any other sources.
  2. Add AI to MkDocs: follow Kapa's own guide to add the widget.
  3. Explore the Configuration options to customize the widget.

Here's one of my mildly spicy docs takes: I really don't like widgets in the bottom right of the site. I think they're visually distracting, potentially get in the way of the content, and have bad associations: how many times have you had a frustrating conversation with a 'help' bot delivered using that type of widget?

This is a quick way to hide the widget and lead users to it through the search bar instead. It isn't perfect: I'd prefer to seamlessly integrate AI and normal search (working on it . . .).

This approach:

  • Sets up the widget, then hides it.

  • Adds a button to the search bar to open the Kapa search. When a user searches, they can click the AI button. This opens the Kapa search modal and pass it the user's search query.

  • Connect Data Sources: connect your documentation site, and any other sources.

  • Add AI to MkDocs: follow Kapa's own guide to add the widget.
  • Having added the widget, hide it by setting script.setAttribute("data-button-hide", true); in init_kapa_widget.js.
  • Override Material for MkDocs' search.html partial:
    1. Follow the Material docs to add an overrides directory if you don't have one already.
    2. In the overrides directory, create partials/search.html.
    3. Copy in the theme's search partial. MkDocs now uses this search partial, rather than the one from the theme.
  • Add a button to your search partial that opens the Kapa AI modal. This button should go inside the search options <nav> element. 
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
    <!-- Search options -->
<nav
class="md-search__options"
aria-label="{{ lang.t('search') }}"
>
<!-- Button to ask Kapa AI -->
<button
    type="button"
    class="md-search__icon md-icon"
    title="Ask AI"
    aria-label="Ask AI"
    tabindex="-1"
    onclick="window.Kapa.open({ query: document.querySelector('[data-md-component=search-query]').value, submit: true })"
>
    {% set icon = config.theme.icon.share or "material/robot" %}
    {% include ".icons/" ~ icon ~ ".svg" %}
</button>
...
    The key part of this code is window.Kapa.open({ query: document.querySelector('[data-md-component=search-query]').value, submit: true }), which takes the user's search query and passes it to the Kapa modal.

"Gif showing a user clicking on the search bar, typing in a query, then clicking a robot icon to open the Kapa search modal"

Your Product Needs Words

Explore ServicesContact Me