How to Add AI to MkDocs

Adding an AI agent to an MkDocs site turns your documentation into something visitors can ask questions of, with answers drawn from your own content and a citation to the source page. With MkDocs, you inject the widget through the theme's extra-JavaScript hook, and the setup takes minutes.

Why MkDocs documentation is a great fit

MkDocs, especially with the Material theme, is a popular home for technical documentation — exactly the content an AI agent answers well. Readers want the specific answer, not a search results page. An agent reads your docs and responds directly, citing the page so the reader can trust it. Well-structured MkDocs content, with its clear navigation and headings, retrieves cleanly. See the documentation use case.

Step 1: Index your documentation

Create an account and get your publishable site key. Then point the platform at your built MkDocs site to crawl, or connect the repository that holds your Markdown. The platform chunks and embeds the content for retrieval at answer time. Schedule a re-crawl so the agent tracks your releases automatically.

Step 2: Add the widget via extra_javascript

MkDocs supports custom scripts through the extra_javascript key in mkdocs.yml. Add a small init script there that loads the AIML.chat embed with your publishable key, and it will appear on every page of the built site. Because it loads asynchronously, it doesn't slow your docs down. Keep the key in your config rather than scattered across pages.

Step 3: Configure a technical agent

Choose a technical agent so answers are precise and developer-focused, returning the relevant snippet and citing the page. Give it a grounded prompt: answer only from indexed docs, cite sources, and escalate when the answer isn't there. Grounding is what keeps it from inventing an option that doesn't exist — see what is RAG.

Step 4: Structure for retrieval

The cleaner your docs, the better the agent answers. Keep pages focused, use clear headings, lead with the answer, and write descriptive titles. Split any page too long to chunk well. These habits improve retrieval and also make your docs easier for humans to navigate.

Step 5: Use the analytics

After launch, the analytics surface the questions readers ask and the ones the agent couldn't answer. That unanswered list is a ready-made documentation backlog — write those pages, re-crawl, and the agent gets better. Support volume becomes a prioritized plan.

What you end up with

Your MkDocs site now answers questions directly, with cited responses, 24/7 and in the reader's language. Developers get unblocked without a ticket, and you learn exactly where your docs are thin. The whole thing runs from one config addition and an indexed crawl. See how to add AI agents to Docusaurus for a related framework.

Why grounding beats a generic widget

Whatever platform you are on, the value is not the chat box — it is that the answers come from your own content. A generic chatbot bolted onto MkDocs will improvise from a general model and confidently get your details wrong, which erodes trust fast. A grounded agent answers only from what you indexed and cites the page, so every reply is traceable to something you actually published. That is the difference between a widget that frustrates visitors and one they come to rely on, and it is why indexing your real content is the step that matters most.

Getting started

Add an agent to your MkDocs site on the AIML.chat free plan: index your docs, add the script via extra_javascript, and configure the agent. Compare tiers on the pricing page.