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.
-
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.jsdocument.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);
});noteReplace 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. -
Update the
conf.py
configuration file inside the Sphinx directory atdocs/source/conf.py
to include the custom JavaScript file:docs/source/conf.pyhtml_static_path = ["_static"]
html_js_files = ["kapa.js"] -
Commit and push these changes to your repository. ReadTheDocs automatically rebuilds your documentation with the new widget integration.
For tailoring the widget position, style, and behavior to your specific needs, refer to the Configuration page.