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
- Your website widget. Kelu makes one for you when you create a knowledge base. Its Install tab shows these steps with your widget id and key already in the code.
- Your site on the widget’s Sites it works on list (Install tab).
Create docs/js/kelu-widget.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/kelu-widget.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 icon button appears in the bottom-right corner, with the tooltip Ask AI. 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 Look tab (choose Follow my site) 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.
