MkDocs runs every file listed under extra_javascript on every page. It cannot put data-* attributes on a script tag, so you add a small file that creates the widget’s tag. This works with any theme, including Material for MkDocs.
Before you start
- A website widget with your site on its Allowed origins list. You need the widget id and public key from its snippet.
Create docs/js/ask-ai.js
(function () {
if (document.getElementById("kelu-widget")) return;
var s = document.createElement("script");
s.id = "kelu-widget";
s.async = true;
s.src = "https://widget.kelu.dev/kelu-widget.js";
s.setAttribute("data-widget-id", "YOUR_WIDGET_ID");
s.setAttribute("data-client-key", "kl_pk_...");
document.head.appendChild(s);
})();
YOUR_WIDGET_ID and kl_pk_... with the values from your widget’s snippet.List it in mkdocs.yml
extra_javascript:
- js/ask-ai.js
extra_javascript already exists, add the line to it.Check locally, then deploy
Run mkdocs serve to see it locally, then build and deploy your site as usual.
Check it works
Open any page. A round Ask AI button appears in the bottom-right corner. Ask a question and check that the answer lists its Sources. Nothing there? See Troubleshooting.
With Material for MkDocs, set Dark-mode selector to [data-md-color-scheme="slate"] on the widget’s Appearance tab to follow the site’s dark mode. On Read the Docs, if some keys do not type in the widget, turn off the Hotkeys and Visual diff addons in your project’s settings.
