Skip to main content

Add AI Chat Widget to ReadTheDocs Documentation - Kapa Integration

Integrate the Kapa Website Widget into your ReadTheDocs documentation to enable users to ask natural language questions about your product, which enhances their experience by providing quick and accurate answers.

Prerequisites

Before adding the widget to your ReadTheDocs site, you'll need to:

  • Ensure you have a Kapa project set up with your knowledge sources added

  • Follow the general installation instructions to enable your domain and obtain your integration ID

  • In ReadTheDocs' Settings, disable the following Addons for your ReadTheDocs website.

    • Visual diff
    • Hotkeys

    These addons interfere with keyboard events on the website, preventing the user from being able to type characters into the Ask AI chat window.

Installation

The installation process for ReadTheDocs involves creating a custom JavaScript file and configuring your Sphinx project to include it.

  1. Create a new JavaScript file in your Sphinx project directory at docs/source/_static/kapa.js for loading and configuring the widget.

    docs/source/_static/kapa.js
    document.addEventListener("DOMContentLoaded", function () {
    var script = document.createElement("script");
    script.src = "https://widget.kapa.ai/kapa-widget.bundle.js";
    script.setAttribute("data-website-id", "YOUR_INTEGRATION_ID");
    script.setAttribute("data-project-name", "YOUR_PROJECT_NAME");
    script.setAttribute("data-project-color", "#HEX_HEX_CODE");
    script.setAttribute("data-project-logo", "https://LINK_TO_LOGO.com/logo.png");
    script.setAttribute("data-button-position-bottom", "120px");
    script.async = true;
    document.head.appendChild(script);
    });
    note

    Replace the placeholder values (YOUR_INTEGRATION_ID, YOUR_PROJECT_NAME, #YOUR_HEX_CODE, etc.) with your actual integration details. You can add or modify widget configuration parameters as needed.

  2. Update the conf.py configuration file inside the Sphinx directory at docs/source/conf.py to include the custom JavaScript file:

    docs/source/conf.py
    html_static_path = ["_static"]
    html_js_files = ["kapa.js"]
  3. Commit and push these changes to your repository. ReadTheDocs automatically rebuilds your documentation with the new widget integration.

Customization options

For tailoring the widget position, style, and behavior to your specific needs, refer to the Configuration page.