Passa al contenuto principale
ChattyBoxInizia gratis

Chatbot AI con citazioni per Docusaurus 3

· 4 minuti di lettura
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

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 protegge questo inserimento specifico dai rimontaggi di React durante lo sviluppo e dai cambi di route lato client. Non rileva un loader separato con un ID diverso o senza ID; usa una sola integrazione per pagina.

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.
  • Per il loader del codice sorgente corrente, https://fonts.googleapis.com in style-src e https://fonts.gstatic.com in font-src quando viene iniettato il foglio di stile di Inter. Un link corrispondente al foglio di stile di Google Fonts impedisce tale iniezione; la sola disponibilità del font non basta. Verifica il comportamento del loader distribuito.
  • L'origine di qualsiasi immagine di icona personalizzata configurata in img-src.
  • 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 domande non supportate e valuta se l'assistente utilizza un fallback invece di inventare una fonte; ripeti con casi rappresentativi senza presumere che ogni risposta si astenga.
  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 conta solo quell'ID; potrebbe comunque esserci un loader separato senza ID o con un ID diverso. Controlla anche tutte le integrazioni e il widget visualizzato. Il conteggio 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​