Author and technical reviewer: Michael Fisher, ChattyBox maintainer. Published and technically checked July 10, 2026 against repository revision 3b0f4d5. The evidence is the runnable example and the repeatable checks below; this is an implementation tutorial, not a performance or accuracy benchmark.

1. Add the Root theme component​

Create src/theme/Root.tsx in your Docusaurus site:

import React, { useEffect, type ReactNode } from 'react';

const WIDGET_ID = 'chattybox-widget';

export default function Root({ children }: { children: ReactNode }) {
  useEffect(() => {
    if (document.getElementById(WIDGET_ID)) return;

    const script = document.createElement('script');
    script.id = WIDGET_ID;
    script.src = 'https://chattybox.ai/widget.js';
    script.async = true;
    script.dataset.apiKey = 'YOUR_API_KEY';
    script.dataset.apiUrl = 'YOUR_CHAT_API_URL';
    script.dataset.chattyboxWidget = 'true';
    document.body.appendChild(script);
  }, []);

  return <>{children}</>;
}

The stable chattybox-widget ID is the important part. React Strict Mode can remount effects during development, and Docusaurus changes routes without replacing the document. The guard makes both cases idempotent.

Use the API URL shown by your ChattyBox project rather than copying an example deployment. See the widget installation reference for the current attributes and the Docusaurus product guide for source-selection and evaluation guidance.

2. Keep the loader mounted​

Do not put this script inside an individual docs page or layout that Docusaurus replaces during navigation. The swizzled Root component wraps the application for its lifetime, so the widget remains available as visitors move between guides and references.

If your site already has src/theme/Root.tsx, merge the effect into the existing component rather than replacing authentication, analytics, or other providers.

3. Account for Content Security Policy​

A restrictive policy needs to allow:

• https://chattybox.ai in script-src for the widget loader.
• Your configured chat API origin in connect-src.
• https://fonts.googleapis.com in style-src and https://fonts.gstatic.com in font-src if the widget font is not already available.
• Inline component styles in style-src for the current widget build.

Start from your existing policy and add only the origins you actually use. Do not replace a restrictive policy with a broad wildcard.

4. Reproduce the integration checks​

The complete sample lives in examples/docusaurus-chattybox. From that directory:

bun install
bun run start

Then verify:

1. Open two different docs routes without a full browser refresh.
2. Run document.querySelectorAll('#chattybox-widget').length after each navigation. It must remain 1.
3. Ask a question answered by an indexed page and confirm the response links to that page.
4. Ask an unsupported question and confirm the assistant falls back instead of inventing a source.
5. Test the launcher at a narrow mobile viewport and check that it does not cover navigation or pagination controls.

The script-count check proves duplicate prevention. It does not prove retrieval quality. Use a representative question set and the scraping guide to validate source coverage before launch.

What to monitor after launch​

Record unresolved questions, incorrect citations, stale source pages, and routes where the launcher obscures site controls. Re-test after Docusaurus theme upgrades because changes to navigation and content layout can affect placement even when the loader remains correct.

For a broader rollout sequence, use the documentation chatbot implementation checklist and launch checklist.

Sources​

• ChattyBox Docusaurus 3 example at revision 3b0f4d5
• Docusaurus swizzling documentation
• MDN Content Security Policy guide

Author and technical reviewer: Michael Fisher, ChattyBox maintainer. Published and technically checked July 10, 2026 against repository revision 3b0f4d5. The original evidence is the two runnable theme examples and the verification protocol below; no traffic, deflection, or answer-accuracy result is claimed.

1. Choose the correct override directory​

For Material for MkDocs, point custom_dir at an overrides directory:

site_name: My documentation
theme:
  name: material
  custom_dir: overrides
  features:
    - navigation.instant

For the built-in theme, use a separate custom theme directory:

site_name: My documentation
theme:
  name: mkdocs
  custom_dir: custom_theme

Keeping the variants separate makes it clear which upstream base template is being extended. The repository sample includes both under examples/mkdocs-chattybox.

2. Extend the scripts block​

Create overrides/main.html for Material or custom_theme/main.html for the built-in theme:

{% 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="YOUR_CHAT_API_URL"
    data-chattybox-widget="true"
  ></script>
{% endblock %}

{{ super() }} preserves scripts provided by the theme, including navigation and search behavior. Omitting it can make the widget appear to work while silently breaking the documentation interface. The stable ID also gives you a direct duplicate-loader assertion.

Use project-specific values from the widget installation reference. The MkDocs AI chatbot guide covers source scope, crawl behavior, and the questions to evaluate before publishing.

3. Build both variants​

From examples/mkdocs-chattybox:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

cd material
mkdocs build --strict

cd ../vanilla
mkdocs build --strict

--strict turns warnings into failures, which catches broken navigation and configuration issues before the widget is evaluated.

4. Run the browser checks​

Serve each variant and verify:

1. Built-in search still opens and returns the expected documentation result.
2. Material instant navigation changes routes without duplicating the widget loader.
3. document.querySelectorAll('#chattybox-widget').length remains 1 after several route changes.
4. At a 390 px viewport, the launcher does not cover search, navigation, or next/previous controls.
5. A supported question cites the expected page, and an unsupported question produces a conservative fallback.

The first four checks validate integration behavior. The fifth depends on the pages you index and requires a representative evaluation set; follow the scraping guide and launch checklist rather than treating a successful script load as proof of answer quality.

5. Preserve a restrictive CSP​

Allow the widget host in script-src, the configured API origin in connect-src, and the font origins in style-src and font-src when needed. The current widget injects component styles, so an otherwise strict policy also needs an explicit inline-style strategy. Avoid wildcard source lists.

Maintenance checklist​

Rebuild both theme variants after MkDocs or Material upgrades, because upstream template block names can change. Keep the script ID stable, preserve super(), and re-run the search, instant-navigation, mobile-overlap, and source-citation checks.

For end-to-end rollout planning, use the documentation chatbot implementation checklist.

Sources​

• ChattyBox MkDocs examples at revision 3b0f4d5
• MkDocs theme customization
• Material for MkDocs customization
• MDN Content Security Policy guide

The product is built for teams that want a practical AI support layer without migrating documentation or rebuilding their site stack. Add your website URL, let ChattyBox crawl published content, test real questions, then install the widget with a script tag.

Why We Built It​

Most website chatbots either require a heavy sales-led setup or answer too broadly from model training data. ChattyBox focuses on the content you already publish, so visitors can ask natural-language questions and still verify the answer against your documentation.

That makes it useful for documentation sites, SaaS help centers, developer docs, CMS pages, and product websites where trust matters.

What Comes Next​

This blog will share practical guides on using AI to reduce support tickets, building reliable RAG chatbots for websites, and adding AI assistants to documentation without losing source control.

Start with the documentation AI chatbot guide or read the installation docs to add ChattyBox to your site.