MkDocs

Add an AI support assistant to an MkDocs site

MkDocs sites — and Material especially — are the reference stack for technical docs. Adding an assistant takes one file and one line of YAML.

One JS file
About two minutes
No config in your app

Get your key Full install docs

docs/js/matterchat.jsfile

// matterchat.js — one file: init, then load the widgetwindow.MatterChat = window.MatterChat || { q: [] };window.MatterChat.q.push(["init", { id: "bot_your_key" }]); var s = document.createElement("script");s.src = "https://app.matterchat.co/widget.js";s.async = true;document.body.appendChild(s);

js · save as its own file

The route through your admin

docs/js/matterchat.js
mkdocs.yml
extra_javascript

The snippet lands in docs/js/matterchat.js.

One file in docs/js, one line of YAML

Save the init-and-load file as docs/js/matterchat.js, add it under extra_javascript in mkdocs.yml, and rebuild. Works identically on plain MkDocs and Material; no theme override needed.

docs/js/matterchat.js: Anything in docs_dir ships with the build, so the file is served from your own site.
extra_javascript: One list entry in mkdocs.yml puts it on every page.
Material instant navigation: The widget lives outside the content area Material swaps, so instant navigation does not disturb it.

Save the file under docs/js/, list it under extra_javascript in mkdocs.yml, and rebuild. On Material with instant navigation, keep the init at top level — it runs once per full load, which is what the widget expects.

What the crawler sees on MkDocs

MkDocs renders static HTML at build time, so every page arrives complete — no JavaScript execution needed on the crawler's side. With the sitemap plugin (on by default in recent MkDocs) discovery is immediate.

The unanswered list is a docs backlog

Questions the assistant refuses — because the docs do not cover them — arrive as a ranked list. For a docs-as-code team that list drops straight into the issue tracker.

Checking it actually worked

Four things, in order. The third is the one people skip, and it is the one that tells you whether the answers are grounded.

1Hard refresh the page — the launcher appears bottom-right.
2Ask it something your site answers, and check the reply cites a page.
3Ask it something your site does not cover, and check it declines.
4Open Conversations in the dashboard; both should be there.

On a different stack?

The snippet is the same everywhere. Only the place you paste it changes.

What MkDocs users ask

Short answers. If yours is not here, the assistant on this page will try it — and tell you honestly if it cannot.

Does it work with Material for MkDocs?

Yes — the extra_javascript route is the same, and no overrides/main.html customisation is required. If you already maintain a theme override, the snippet can live in the scripts block instead; both work.

Do I need the Insiders edition?

No. extra_javascript is core MkDocs, available to every plan and theme.

Can it answer from more than the docs?

Yes — crawl the marketing site alongside, or upload PDFs and internal runbooks; every source is cited by the page or file the answer came from.