Add an Ask AI box to a MkDocs site

Q: Do I need to install a plugin?

No. extra_javascript is a standard MkDocs setting and takes a URL. Nothing is added to your Python environment or your build.

How do I let readers ask questions of my MkDocs or Material for MkDocs documentation and get answers from its pages?

MkDocs already writes a full-text index of your site, search/search_index.json, for its search box. That index is all an AI answer needs: the sections that match a question, and a model to write the answer from them.

The OneTag AI ask-docs.js script does exactly that in the reader's browser. You add one line to mkdocs.yml. There is no plugin to install, no build step, and no service that crawls your site. A live example, with its whole documentation: Ask AI for MkDocs.

Steps

Get a free key
From onetagai.com: enter your email and open the link you are sent. The key starts with ot_.
Add one line to mkdocs.yml
```
extra_javascript:
  - https://onetagai.com/ask-docs.js?key=YOUR_ONETAG_KEY
```
If you already have an extra_javascript list, add the line to it.
Build and ask
Run mkdocs serve. On Material for MkDocs an Ask AI button appears in the header next to search; on the built-in mkdocs and readthedocs themes it floats in the bottom right corner. Ask something your docs answer: the answer comes with links to the sections it was written from.

What happens when a reader asks

The script fetches the search index the first time the box is opened, not on page load. It scores every section of the site against the words of the question, and sends the eight best, up to 20,000 characters, to OneTag AI with the question. The answer streams back, with up to three source links under it. A question in a language your docs are not written in is first turned into search keywords, and answered in the language it was asked in.

Keep the search plugin on

The index comes from MkDocs' search plugin, which is on by default. If you set plugins: yourself, keep search in the list. Without the index the box still works, but answers only from the page the reader is on.

Options

Options are query parameters on the same URL: label, placeholder, position (auto, float, left, none), button (your own element that opens the box), color, theme, lang, rules (replaces what the AI is told) and index. They are listed in the docs.

extra_javascript:
  - https://onetagai.com/ask-docs.js?key=YOUR_ONETAG_KEY&label=Ask%20the%20docs&position=float

Cost

A question costs 1,000 to 3,000 tokens on a typical site and at most about 6,000. A free key has 1,000,000 tokens a month, roughly 300 to 1,000 questions. When the allowance runs out the box says so and lists the pages that match the question, so readers still reach the right page.

Questions

Do I need to install a plugin?

No. extra_javascript is a standard MkDocs setting and takes a URL. Nothing is added to your Python environment or your build.

Does it work with Material's instant navigation?

Yes. The script loads once, keeps the conversation while the reader moves between pages, and puts its button back when Material rebuilds the header.

Does it work when the site is in a subfolder, like username.github.io/project/?

Yes. The index is found relative to the site, not to the domain root. It also works with use_directory_urls: false.

My docs are not in English. Does it work?

Yes. Chinese, Japanese and Korean text is matched without needing spaces between words, and the answer is in the language of the question.

Can I see what readers ask?

No. OneTag AI does not store questions or answers; it only counts the tokens a key uses.

Is it safe to put the OneTag AI key in my page?

Yes, it is designed for that. The key can only spend its own token budget and cannot read or change anything on your account. On the Pro plan you can lock it to your domain so other sites cannot use it; free keys work from any page.

Which model answers?

A fast, inexpensive model from OpenRouter, chosen for sub-second first tokens and good instruction following. You do not pick a model; the point is one tag that keeps working.

What happens to the text my visitors send?

It goes to the model and comes back. OneTag AI stores token counts per key for the quota and keeps no prompts, inputs or answers. The access log carries no IP addresses.

Try it on your sitefree

Get a free key by email, paste one tag, call onetag.ask. 1,000,000 tokens a month, no card.

Get a free key

Updated 2026-11-11. Something wrong or missing? Email support@odysseyx.app.