Author and technical reviewer: Michael Fisher, ChattyBox maintainer. Published and technically checked July 10, 2026. The repeatable checks below are 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​

In your Docusaurus project, add the Root wrapper above and run:

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 widget installation reference
• Docusaurus swizzling documentation
• MDN Content Security Policy guide

Author and technical reviewer: Michael Fisher, ChattyBox maintainer. Published and technically checked July 10, 2026. The verification protocol below is an implementation tutorial; 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.

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 your MkDocs project:

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 widget installation reference
• MkDocs theme customization
• Material for MkDocs customization
• MDN Content Security Policy guide

O produto foi criado para equipas que querem uma camada prática de suporte com IA sem migrar documentação nem reconstruir a stack do site. Adicione o URL do seu site, deixe o ChattyBox rastrear o conteúdo publicado, teste perguntas reais e instale depois o widget com uma tag script.

Porque o criámos​

A maioria dos chatbots para sites exige uma configuração pesada orientada por vendas ou responde de forma demasiado ampla a partir dos dados de treino do modelo. O ChattyBox foca-se no conteúdo que já publica, para que os visitantes possam fazer perguntas em linguagem natural e ainda verificar a resposta na sua documentação.

Isto é útil para sites de documentação, centros de ajuda SaaS, documentação para programadores, páginas CMS e sites de produto onde a confiança importa.

O que vem a seguir​

Este blog vai partilhar guias práticos sobre usar IA para reduzir tickets de suporte, criar chatbots RAG fiáveis para sites e adicionar assistentes de IA à documentação sem perder o controlo das fontes.

Comece pelo guia de chatbot de IA para documentação ou leia a documentação de instalação para adicionar o ChattyBox ao seu site.