Skip to main content

Add a Source-Cited AI Chatbot to Docusaurus 3

· 4 min read
Michael Fisher
ChattyBox maintainer and technical writer

Docusaurus behaves like a single-page application after the first page load. A widget integration that only works on the initial document, or that appends a second loader on every route change, is not production-ready. This guide uses a stable script identity and a theme root that remains mounted across documentation routes.

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 guards this particular insertion against React development remounts and client-side route changes. It does not detect a separate loader with a different or missing ID; use only one integration per page.

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.
  • For the current-source loader, https://fonts.googleapis.com in style-src and https://fonts.gstatic.com in font-src when it injects the Inter stylesheet. A matching Google Fonts stylesheet link prevents that injection; an otherwise available font alone does not. Verify the deployed loader's behavior.
  • The origin of any configured custom icon image in img-src.
  • 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 unsupported questions and evaluate whether the assistant falls back instead of inventing a source; repeat with representative cases rather than assuming every response will abstain.
  5. Test the launcher at a narrow mobile viewport and check that it does not cover navigation or pagination controls.

The script-count check only counts that ID; a separate unmarked or differently named loader may still exist. Check all integrations and the rendered widget too. The count 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​