Chatbot AI con citazioni per Docusaurus 3

Docusaurus si comporta come un'applicazione a pagina singola dopo il primo caricamento. Un'integrazione del widget che funziona solo sul documento iniziale, o che aggiunge un secondo loader a ogni cambio di percorso, non è pronta per la produzione. Questa guida utilizza un'identità stabile per lo script e una radice del tema che rimane montata in tutte le route della documentazione.

Autore e revisore tecnico: Michael Fisher, responsabile di ChattyBox. Pubblicato e verificato tecnicamente il 10 luglio 2026. Le verifiche ripetibili riportate di seguito sono un tutorial di implementazione, non un benchmark di prestazioni o accuratezza.

1. Aggiungi il componente Root del tema

Crea src/theme/Root.tsx nel tuo sito Docusaurus:

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}</>;
}

L'ID stabile chattybox-widget è l'elemento importante. React Strict Mode può rimontare gli effect durante lo sviluppo e Docusaurus cambia route senza sostituire il documento. Il controllo rende idempotenti entrambi i casi.

Usa l'URL dell'API mostrato dal tuo progetto ChattyBox invece di copiare un deployment di esempio. Consulta il riferimento per l'installazione del widget per gli attributi attuali e la guida al prodotto Docusaurus per indicazioni sulla selezione delle fonti e sulla valutazione.

2. Mantieni il loader montato

Non inserire questo script in una singola pagina della documentazione o in un layout che Docusaurus sostituisce durante la navigazione. Il componente Root sottoposto a swizzling avvolge l'applicazione per tutta la sua durata, quindi il widget rimane disponibile mentre i visitatori passano tra guide e riferimenti.

Se il tuo sito ha già src/theme/Root.tsx, integra l'effect nel componente esistente invece di sostituire i provider di autenticazione, analytics o altri provider.

3. Considera la Content Security Policy

Una policy restrittiva deve consentire:

• https://chattybox.ai in script-src per il loader del widget.
• L'origine dell'API di chat configurata in connect-src.
• https://fonts.googleapis.com in style-src e https://fonts.gstatic.com in font-src se il font del widget non è già disponibile.
• Gli stili inline dei componenti in style-src per la build corrente del widget.

Parti dalla policy esistente e aggiungi solo le origini che utilizzi davvero. Non sostituire una policy restrittiva con un wildcard ampio.

4. Ripeti le verifiche di integrazione

Nel tuo progetto Docusaurus, aggiungi il wrapper Root precedente ed esegui:

bun install
bun run start

Poi verifica:

1. Apri due route diverse della documentazione senza ricaricare completamente il browser.
2. Esegui document.querySelectorAll('#chattybox-widget').length dopo ogni navigazione. Deve rimanere 1.
3. Fai una domanda a cui risponde una pagina indicizzata e verifica che la risposta rimandi a quella pagina.
4. Fai una domanda non supportata e verifica che l'assistente utilizzi un fallback invece di inventare una fonte.
5. Prova il launcher a una viewport mobile stretta e controlla che non copra i controlli di navigazione o paginazione.

Il controllo del numero di script dimostra la prevenzione dei duplicati. Non dimostra la qualità del recupero. Usa un set rappresentativo di domande e la guida allo scraping per convalidare la copertura delle fonti prima del lancio.

Cosa monitorare dopo il lancio

Registra le domande senza risposta, le citazioni errate, le pagine sorgente obsolete e le route in cui il launcher nasconde i controlli del sito. Ripeti i test dopo gli aggiornamenti del tema Docusaurus, perché i cambiamenti alla navigazione e al layout dei contenuti possono influire sul posizionamento anche quando il loader rimane corretto.

Per una sequenza di rilascio più ampia, usa la checklist di implementazione del chatbot per la documentazione e la checklist di lancio.

Fonti

• Riferimento per l'installazione del widget ChattyBox
• Documentazione sullo swizzling di Docusaurus
• Guida di MDN alla Content Security Policy