Chatbot AI con citazioni per MkDocs
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 fornisce anche un'asserzione diretta contro i loader duplicati.
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
Dal tuo progetto MkDocs:
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:
- La ricerca integrata continua ad aprirsi e restituisce il risultato atteso della documentazione.
- La navigazione istantanea di Material cambia route senza duplicare il loader del widget.
document.querySelectorAll('#chattybox-widget').lengthrimane1dopo diversi cambi di route.- A una viewport di 390 px, il launcher non copre ricerca, navigazione o i controlli precedente/successivo.
- Una domanda supportata cita la pagina prevista e una domanda non supportata produce un fallback prudente.
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 le origini dei font in style-src e font-src quando necessario. 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.