Passa al contenuto principale
ChattyBoxInizia gratis

Chatbot AI con citazioni per MkDocs

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

I temi MkDocs espongono directory di override diverse e Material può passare da una pagina all'altra senza un ricaricamento completo. Un'integrazione duratura deve conservare gli script esistenti del tema, caricare il widget una sola volta e funzionare insieme a ricerca e navigazione sui dispositivi mobili.

Autore e revisore tecnico: Michael Fisher, responsabile di ChattyBox. Pubblicato e verificato tecnicamente il 10 luglio 2026. Il protocollo di verifica seguente è un tutorial di implementazione; non viene dichiarato alcun risultato relativo a traffico, deflessione o accuratezza delle risposte.

1. Scegli la directory di override corretta​

Per Material for MkDocs, imposta custom_dir sulla directory overrides:

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

Per il tema integrato, usa una directory separata per il tema personalizzato:

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

Mantenere separate le varianti chiarisce quale template di base upstream viene esteso.

2. Estendi il blocco scripts​

Crea overrides/main.html per Material oppure custom_theme/main.html per il tema integrato:

{% 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() }} conserva gli script forniti dal tema, inclusi i comportamenti di navigazione e ricerca. Ometterlo può far sembrare che il widget funzioni mentre rompe silenziosamente l'interfaccia della documentazione. L'ID stabile aiuta a contare questo script; non rileva un altro loader con un ID diverso o senza ID.

Usa i valori specifici del progetto indicati nel riferimento per l'installazione del widget. La guida al chatbot AI per MkDocs tratta l'ambito delle fonti, il comportamento del crawling e le domande da valutare prima della pubblicazione.

3. Esegui la build di entrambe le varianti​

Scarica ed estrai gli esempi MkDocs, poi esegui questi comandi dalla directory estratta examples/mkdocs-chattybox. Contiene requirements.txt e i progetti separati material e vanilla. Per un progetto esistente, usa invece le sue dipendenze e la sua directory.

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

cd material
mkdocs build --strict

cd ../vanilla
mkdocs build --strict

--strict trasforma gli avvisi in errori, così intercetta i problemi di navigazione e configurazione prima che venga valutato il widget.

4. Esegui le verifiche nel browser​

Servi entrambe le varianti e verifica:

  1. La ricerca integrata continua ad aprirsi e restituisce il risultato atteso della documentazione.
  2. La navigazione istantanea di Material cambia route senza duplicare il loader del widget.
  3. document.querySelectorAll('#chattybox-widget').length rimane 1 dopo diversi cambi di route.
  4. A una viewport di 390 px, il launcher non copre ricerca, navigazione o i controlli precedente/successivo.
  5. Una domanda supportata cita la pagina prevista; verifica il comportamento di fallback prudente con domande non supportate, senza presumere che ogni risposta si astenga.

Il conteggio dell'ID riguarda solo quello script; controlla anche le altre integrazioni e il widget visualizzato per individuare duplicati. Le prime quattro verifiche convalidano il comportamento dell'integrazione. La quinta dipende dalle pagine indicizzate e richiede un set di valutazione rappresentativo; segui la guida allo scraping e la checklist di lancio invece di considerare il caricamento riuscito dello script una prova della qualità delle risposte.

5. Mantieni una CSP restrittiva​

Consenti l'host del widget in script-src, l'origine dell'API configurata in connect-src e l'origine di qualsiasi immagine di icona personalizzata in img-src. Per il widget v16 del codice sorgente corrente, consenti le origini di Google Fonts in style-src e font-src quando viene iniettato il foglio di stile di Inter; verifica il comportamento del loader distribuito. Il widget corrente inietta gli stili dei componenti, quindi una policy altrimenti rigida richiede anche una strategia esplicita per gli stili inline. Evita gli elenchi di origini wildcard.

Checklist di manutenzione​

Ricostruisci entrambe le varianti del tema dopo gli aggiornamenti di MkDocs o Material, perché i nomi dei blocchi nei template upstream possono cambiare. Mantieni stabile l'ID dello script, conserva super() e ripeti le verifiche di ricerca, navigazione istantanea, sovrapposizione su mobile e citazione delle fonti.

Per pianificare il rilascio end-to-end, usa la checklist di implementazione del chatbot per la documentazione.

Fonti​