MkDocs Integration

Add the Asyntai AI chat assistant to your MkDocs documentation site

Overview

MkDocs builds documentation sites from Markdown. The Asyntai integration is a MkDocs plugin. Add it to mkdocs.yml, build the site, and the chat bubble is on every page.

The assistant answers your readers from your own documentation, day and night. It works with every MkDocs theme, including Material for MkDocs and Read the Docs.

Requirements

MkDocs 1.4 or later
Python 3.8 or later
An Asyntai account. The Free plan is enough to try the widget

Installation

Follow these steps to add Asyntai to your MkDocs site:

Get Your Widget ID

Sign in to Asyntai and open the Install page. The widget ID is the value of data-asyntai-id in the snippet shown there. It starts with asyntai_.

Install the Plugin

Run this command in the environment where you build your docs:

pip install mkdocs-ai-chatbot

If your site builds in CI, add mkdocs-ai-chatbot to your requirements.txt as well.

Add It to mkdocs.yml

Open mkdocs.yml and add the plugin with your widget ID:

plugins:
  - search
  - asyntai:
      widget_id: asyntai_1a2b3c4d5e6f

Keep search in the list if you use it. When mkdocs.yml has a plugins section, MkDocs only loads the plugins named there.

Build the Site

Run mkdocs build and publish, or run mkdocs gh-deploy. Open your site and the chat bubble is in the corner of every page.

Options

Option	Type	Default	What it does
`widget_id`	string	required	Your Asyntai widget ID
`enable_on_serve`	boolean	`true`	Set it to `false` to keep the widget off the site during `mkdocs serve`
`script_url`	string	the Asyntai CDN	Advanced. Load the widget from another URL

A missing or malformed widget_id stops the build with a message that says how to fix it.

How It Works

The plugin adds one async script tag at the end of every page your site builds, so your documentation always renders first. The 404 page gets the chat too, so a reader on a broken link can still ask a question.

With Material for MkDocs, the widget stays open when a reader moves between pages with instant navigation. No theme files are overridden and no CSS is added.

Answering From Your Documentation

Asyntai reads your published pages. Add your site URL in the dashboard, and the assistant answers from the same documentation the widget sits on. You can also add documents, and question and answer pairs.

Tip: Set enable_on_serve: false while you write. The widget then shows up only on the built site.

Removing It

Delete the asyntai entry from mkdocs.yml and build again. The chat bubble is gone.

Plans & Pricing

The plugin is free. View pricing.

Need Help?

If you have any questions or run into issues, contact us at [email protected].