MkDocs Support Bot

MkDocs AI Chatbot for MkDocs Documentation

An AI chatbot for MkDocs and Material for MkDocs documentation. ChattyBox crawls your public site, answers questions like "How do I enable navigation tabs?" from those pages, and cites the source. No Python indexing pipeline or custom RAG to maintain.

Crawls published docs pages

Source-cited answers

Embeds with one script

No docs migration required

Create a MkDocs AI chatbot free Read setup guide

No credit card requiredYour content stays yours

Ask ChattyBox

Where should I start if I need a reliable answer from this site?

Start by adding your website URL to ChattyBox. It crawls your content, answers from the pages it finds, and shows visitors the sources behind each response.

iSources3^

MkDocs guide

chattybox.ai

Analytics

chattybox.ai

Home

chattybox.ai

Ask a question...

Built for MkDocs teams

Launch a source-cited chatbot without rebuilding your docs stack

ChattyBox crawls your existing documentation, indexes the content for retrieval, and embeds a chatbot that answers using your docs instead of generic model memory.

The Material override preserves theme JavaScript and adds one asynchronous widget loader.

Vanilla MkDocs uses a separate custom theme directory instead of assuming Material paths.

Checks cover search coexistence, instant navigation, duplicate loaders, and narrow mobile viewports.

Version-aware crawl selection keeps stable, latest, and legacy mike routes deliberate.

Workflow step

Crawl the deployed MkDocs sitemap or the stable and versioned paths you intentionally support.

Workflow step

Test product, Python, and API questions and open every citation before installation.

Workflow step

For Material, configure theme.custom_dir and extend base.html from overrides/main.html while preserving the scripts block with super().

Workflow step

Verify built-in search, instant navigation, mobile controls, CSP, and each published mike version.

Three-step launch

Paste your MkDocs URL, test cited answers, then install the widget.

Create a MkDocs AI chatbot free

MkDocs-specific workflow

Conversational support for static Python documentation sites

MkDocs teams usually want fast static builds, clear navigation, and readable technical content. ChattyBox keeps that workflow intact while adding a source-cited assistant on top of the published site.

Decision path

Use these checkpoints to decide whether ChattyBox should sit beside your docs platform, replace a separate assistant, or stay isolated for testing.

Works with Material for MkDocs pages

Index guides, reference pages, and generated static HTML from public MkDocs or Material for MkDocs deployments without replacing your theme.

Handle versioned documentation deliberately

Point ChattyBox at the version paths you want users to ask about, then test whether answers cite the intended stable, latest, or legacy docs.

No Python indexing job to maintain

Because ChattyBox crawls the public site, teams do not need to add vector indexing to their MkDocs build pipeline or CI scripts.

Improve docs from real questions

Use unanswered questions to identify missing examples, unclear installation steps, or outdated troubleshooting pages in your MkDocs site.

Tested editorial evidence

Tested Material and vanilla MkDocs installation paths

Material for MkDocs and the built-in MkDocs theme both support template inheritance, but they should use separate custom directories. The Material path below preserves its scripts block with super(), adds one async loader, and survives instant navigation without replacing search behavior.

Technical author: ChattyBox Documentation Team
Technical reviewer: ChattyBox Engineering
Last updated: 2026-07-09
Information checked: MkDocs, Material for MkDocs, and mike

Recheck template blocks and instant-navigation behavior after theme upgrades, and recrawl whenever a mike alias moves.

Material for MkDocs custom_dir configuration and main template override preserving theme scripts — Original installation reference: theme.custom_dir selects the override and super() keeps Material search and navigation scripts intact.

Material and vanilla MkDocs installation decisions with end-to-end checks.
MkDocs concern	Implementation decision	Verification
Material override	Set theme.name to material and theme.custom_dir to overrides. Extend base.html, override scripts, call super(), then append the widget script.	Build and serve the site, then confirm Material search and navigation still work.
Vanilla MkDocs	Use theme.name: mkdocs with a separate custom_theme directory. Add the equivalent custom_theme/main.html override rather than copying Material templates.	Run mkdocs serve and verify search, next and previous links, and the widget on more than one page.
Async loading and duplicates	Keep one loader in the inherited scripts block, give it a stable ID, and do not add the same snippet through extra_javascript or another partial.	After full loads and Material instant transitions, confirm document.querySelectorAll("#chattybox-widget").length is 1.
Content Security Policy	Allow chattybox.ai in script-src, the configured API origin in connect-src, fonts.googleapis.com in style-src, and fonts.gstatic.com in font-src. The current widget injects its component CSS, so a strict style-src also needs 'unsafe-inline' until a nonce-aware or external stylesheet build is available.	Check the browser console and Network panel for blocked script, style, font, fetch, or WebSocket requests.
Search, instant navigation, and mobile	Preserve theme scripts with super() and keep the launcher clear of the search dialog, drawer, pagination, and consent controls.	Test keyboard search, several instant links, and a 390-pixel viewport with no overlap or horizontal scrolling.
mike versions	Choose stable, latest, or explicit version paths deliberately. Recrawl after moving an alias, and exclude unsupported releases when cross-version answers would mislead users.	Use mike serve to test version switching and confirm citations resolve inside the intended version.
Widget or citation failure	Check YAML indentation, the active custom_dir, inherited block name, API key, CSP, sitemap contents, and whether the deployed build includes the override.	Inspect generated HTML and test the production artifact instead of relying only on live reload.

Cited-answer check

Test an answer against the active version

Use a theme question with a verifiable template rule, then open the citation and confirm it matches the version your visitor selected.

Ask the MkDocs guides

How do I add the widget without breaking Material search?

Set theme.custom_dir to overrides, create overrides/main.html, extend base.html, and add the async loader inside the scripts block after super(). Calling super() preserves the scripts Material uses for search and navigation.

iSources2^

Material: customization

squidfunk.github.io/mkdocs-material

MkDocs: customizing your theme

mkdocs.org/user-guide

Ask a question...

Original mobile reference: search remains available, the launcher has a usable touch target, and the page does not scroll horizontally.

Primary sources and reproducible evidence

Material for MkDocs customizationOfficial custom_dir, template inheritance, and block override guidance.Material instant navigationOfficial behavior for document replacement without a full page reload.MkDocs theme customizationOfficial custom theme directory, base template, and super() guidance for vanilla MkDocs.mike versioned documentationVersion deployment, aliases, default version, and local multi-version testing.Reproducible MkDocs examplesSeparate Material and vanilla projects with tested template overrides.

Install path

How to add the widget to MkDocs

For Material for MkDocs, set theme.custom_dir to overrides, extend base.html in overrides/main.html, and call super() before the async widget script. Vanilla MkDocs needs its own custom theme directory and equivalent main.html override.

1Create a ChattyBox project and enter your MkDocs or Material for MkDocs site URL or sitemap.
2Test real MkDocs questions in the dashboard and confirm citations point to the right pages.
3Add the tested override, build the site, and verify search, navigation, CSP, and mobile behavior.

Create a MkDocs AI chatbot free

overrides/main.html

html

{% extends "base.html" %}

{% block scripts %}
  {{ super() }}
  <script
    id="chattybox-widget"
    src="https://chattybox.ai/widget.js"
    async
    data-api-key="YOUR_API_KEY"
    data-api-url="https://adorable-woodpecker-629.convex.site/chat"
    data-chattybox-widget="true"
  ></script>
{% endblock %}

Explore next

More ways to use ChattyBox

Explore all solutions

AI chatbot for documentation

See the source-cited documentation chatbot workflow that applies across platforms.

Open

API documentation chatbot

Answer endpoint, parameter, and authentication questions from Python and API reference docs.

Open

Docusaurus AI chatbot

Compare the same grounded workflow for Docusaurus documentation sites.

Open

Browse all platform guides

Find setup guides for Docusaurus, VitePress, Starlight, Nextra, Mintlify, ReadMe, and more docs platforms.

Open

FAQ

Common questions

Does ChattyBox work with Material for MkDocs?

Yes. ChattyBox can crawl public MkDocs and Material for MkDocs pages and embed as a standard website widget.

Do I need to change my Python build pipeline?

No. Add the widget snippet to your site template or theme override after configuring the chatbot.

Can the bot answer from versioned docs?

Yes, if versioned docs pages are public and included in the crawl or sitemap.

Can it identify documentation gaps?

Yes. ChattyBox analytics help reveal questions that your MkDocs content does not answer clearly yet.

Start free

No credit card required. Your content is not used for model training.

Create free chatbot

Free tier. No card needed.