Passa al contenuto principale
Bot di supporto per MkDocs

Aggiungi un chatbot AI con citazioni delle fonti alla tua documentazione MkDocs e Material

Un chatbot IA per la documentazione MkDocs e Material for MkDocs. ChattyBox esegue la scansione del tuo sito pubblico e può inserire nelle risposte link alle pagine recuperate. Verifica l'accuratezza delle risposte e delle citazioni. Nessuna pipeline di indicizzazione Python o sistema RAG personalizzato da mantenere.

Esegue la scansione delle pagine dei documenti pubblicatiRisposte con citazioni delle fontiIncorpora con uno scriptNon è richiesta la migrazione dei documentiNessuna carta di credito richiestaI tuoi contenuti restano tuoi
Chiedi a ChattyBox
Da dove dovrei iniziare se mi serve una risposta affidabile da questo sito?
Inizia aggiungendo l’URL pubblico del sito a ChattyBox. Recupera contenuti indicizzati per guidare le risposte e può mostrare link alle pagine fonte da verificare. Prova risposte e fallback prima del lancio.
iFonti3^
MkDocs guida
chattybox.ai
Analisi
chattybox.ai
Pagina iniziale
chattybox.ai

Conversazione a scopo illustrativo — non è una chat dal vivo.

Offerto da ChattyBox

Lancia un chatbot con citazioni delle fonti senza ricostruire lo stack del tuo sito

ChattyBox esegue la scansione del tuo sito web esistente, della documentazione, del centro assistenza, del CMS o della knowledge base. I contenuti recuperati possono guidare le risposte del chatbot; verifica l'accuratezza delle risposte e delle citazioni.

L'override di Material preserva il JavaScript del tema e aggiunge un caricatore asincrono del widget.
Vanilla MkDocs utilizza una directory di temi personalizzata separata invece di assumere percorsi Material.
I controlli riguardano la coesistenza della ricerca, la navigazione istantanea, i caricatori duplicati e le finestre mobili ristrette.
La selezione della scansione in base alla versione mantiene deliberati i percorsi mike stabili, più recenti e legacy.
Passaggio del workflow

Esegui la scansione della mappa del sito MkDocs distribuita o dei percorsi stabili e con versione che supporti intenzionalmente.

Passaggio del workflow

Testare le domande sul prodotto, Python e API e aprire ogni citazione prima dell'installazione.

Passaggio del workflow

Per Material, configura theme.custom_dir ed estendi base.html da overrides/main.html preservando il blocco degli script con super().

Passaggio del workflow

Verifica la ricerca integrata, la navigazione istantanea, i controlli mobili, CSP e ciascuna versione mike pubblicata.

Lancio in tre fasi

Incolla l'URL MkDocs, prova le risposte con citazioni delle fonti, quindi installa il widget.

Flusso di lavoro specifico di MkDocs

Supporto conversazionale per siti di documentazione Python statici

I team di MkDocs di solito desiderano build statiche veloci, navigazione chiara e contenuti tecnici leggibili. ChattyBox mantiene intatto il flusso di lavoro aggiungendo al sito pubblicato un assistente che cita le fonti.

Percorso decisionale

Utilizza questi punti di controllo per decidere se ChattyBox deve essere affiancato alla tua piattaforma di documenti, sostituire un assistente separato o rimanere isolato per i test.

01

Funziona con le pagine Material for MkDocs

Indicizza guide, pagine di riferimento e HTML statico generato da siti pubblici MkDocs o Material for MkDocs senza sostituire il tema.

02

Gestire deliberatamente la documentazione con versione

Indica a ChattyBox i percorsi delle versioni su cui gli utenti porranno domande, quindi verifica che le risposte citino la documentazione prevista, stabile, più recente o legacy.

03

Nessun lavoro di indicizzazione Python da mantenere

Poiché ChattyBox esegue la scansione del sito pubblico, i team non devono aggiungere l'indicizzazione vettoriale alla pipeline di build MkDocs o agli script CI.

04

Migliora i documenti partendo da domande reali

Su Pro o Business, esamina le domande segnalate come indicatori euristici di possibili esempi mancanti, passaggi di installazione poco chiari o pagine di risoluzione dei problemi obsolete.

Evidenze editoriali verificate

Percorsi di installazione Material e vanilla MkDocs testati

Material for MkDocs e il tema MkDocs integrato supportano entrambi l'ereditarietà dei modelli, ma dovrebbero utilizzare directory personalizzate separate. Il percorso Material riportato di seguito conserva il blocco di script con super(), aggiunge un caricatore asincrono e sopravvive alla navigazione istantanea senza sostituire il comportamento di ricerca.

Autore tecnico
Team di documentazione ChattyBox
Revisore tecnico
ChattyBox Ingegneria
Ultimo aggiornamento
Informazioni verificate
MkDocs, Material for MkDocs e mike

Ricontrolla i blocchi dei modelli e il comportamento della navigazione istantanea dopo gli aggiornamenti del tema e ripeti la scansione ogni volta che un alias mike si sposta.

Configurazione custom_dir di Material for MkDocs e override del template principale che preserva gli script del tema
Riferimento all'installazione originale: theme.custom_dir seleziona l'override e super() mantiene intatti gli script di ricerca e navigazione Material.
Decisioni sull'installazione di Material e vanilla MkDocs con controlli end-to-end.
Preoccupazione MkDocsDecisione di attuazioneVerifica
Preoccupazione MkDocs
Sostituzione Material
Decisione di attuazione
Imposta theme.name su material e theme.custom_dir su overrides. Estendi base.html, applica l'override al blocco scripts, chiama super(), quindi aggiungi lo script del widget.
Verifica
Costruisci e offri il sito, quindi verifica che la ricerca e la navigazione Material funzionino ancora.
Preoccupazione MkDocs
MkDocs standard
Decisione di attuazione
Utilizza theme.name: mkdocs con una directory custom_theme separata. Aggiungi l'override custom_theme/main.html equivalente anziché copiare i modelli Material.
Verifica
Esegui mkdocs serve e verifica la ricerca, i collegamenti successivo e precedente e il widget su più di una pagina.
Preoccupazione MkDocs
Caricamento asincrono e duplicati
Decisione di attuazione
Mantieni un caricatore nel blocco degli script ereditati, assegnagli un ID stabile e non aggiungere lo stesso snippet tramite extra_javascript o un altro partial.
Verifica
Dopo i carichi completi e le transizioni istantanee Material, verificare che document.querySelectorAll("#chattybox-widget").length sia 1.
Preoccupazione MkDocs
Content Security Policy
Decisione di attuazione
Consenti chattybox.ai in script-src, l'origine API configurata in connect-src, fonts.googleapis.com in style-src e fonts.gstatic.com in font-src. Il widget attuale inietta il CSS del componente, quindi uno style-src restrittivo richiede anche 'unsafe-inline' finché non sarà disponibile una build con nonce o con un foglio di stile esterno.
Verifica
Controlla la console del browser e il pannello Network per verificare la presenza di richieste di script, stile, font, fetch o WebSocket bloccate.
Preoccupazione MkDocs
Ricerca, navigazione istantanea e dispositivi mobili
Decisione di attuazione
Conserva gli script dei temi con super() e mantieni il launcher lontano dalla finestra di dialogo di ricerca, dal drawer, dall'impaginazione e dai controlli di consenso.
Verifica
Prova la ricerca tramite tastiera, diversi collegamenti istantanei e un viewport da 390 pixel senza sovrapposizioni o scorrimento orizzontale.
Preoccupazione MkDocs
Versioni mike
Decisione di attuazione
Scegli deliberatamente percorsi di versione stabili, più recenti o espliciti. Ripeti la scansione dopo aver spostato un alias ed escludi versioni non supportate quando le risposte a versioni incrociate potrebbero fuorviare gli utenti.
Verifica
Utilizza mike serve per testare il cambio di versione e confermare che le citazioni si risolvono all'interno della versione prevista.
Preoccupazione MkDocs
Errore nel widget o nella citazione
Decisione di attuazione
Controlla il rientro YAML, la custom_dir attiva, il nome del blocco ereditato, la chiave API, CSP, il contenuto della mappa del sito e se la build distribuita include l'override.
Verifica
Ispeziona lo HTML generato e testa l'artefatto di produzione invece di fare affidamento solo sulla ricarica in tempo reale.
Controllo della risposta citata

Testare una risposta rispetto alla versione attiva

Utilizza una domanda sul tema con una regola del modello verificabile, quindi apri la citazione e verifica che corrisponda alla versione selezionata dal visitatore.

Lista di controllo pratica per valutare i chatbot IA per la documentazione
Chiedi alle guide MkDocs
Come faccio ad aggiungere il widget senza interrompere la ricerca Material?
Imposta theme.custom_dir su overrides, crea overrides/main.html, estendi base.html e aggiungi il caricatore asincrono all'interno del blocco degli script dopo super(). La chiamata a super() preserva gli script utilizzati da Material per la ricerca e la navigazione.

Conversazione a scopo illustrativo — non è una chat dal vivo.

Offerto da ChattyBox
Pagina mobile Material for MkDocs con ricerca e ChattyBox visibili senza controlli sovrapposti
Riferimento mobile originale: la ricerca rimane disponibile, il launcher ha un touch target utilizzabile e la pagina non scorre orizzontalmente.
Percorso di installazione

Come aggiungere il widget a MkDocs

Per Material for MkDocs, imposta theme.custom_dir su overrides, estendi base.html in overrides/main.html e chiama super() prima dello script asincrono del widget. MkDocs vanilla richiede una directory di tema personalizzata separata e un override main.html equivalente.

  1. 1Crea un progetto ChattyBox e inserisci l'URL del sito o la mappa del sito MkDocs o Material for MkDocs.
  2. 2Prova le domande reali di MkDocs nella dashboard e verifica che le citazioni puntino alle pagine giuste.
  3. 3Aggiungi l'override testato, compila il sito e verifica ricerca, navigazione, CSP e comportamento su mobile.
overrides/main.html
html
{% 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="https://adorable-woodpecker-629.convex.site/chat"
    data-chattybox-widget="true"
  ></script>
{% endblock %}
Domande frequenti

Domande comuni

1

ChattyBox funziona con Material for MkDocs?

Sì. ChattyBox può eseguire la scansione delle pagine pubbliche MkDocs e Material for MkDocs ed essere incorporato come normale widget per siti web.

2

Devo modificare la pipeline di compilazione di Python?

No. Dopo aver configurato il chatbot, aggiungi lo snippet del widget al template del sito o a un override del tema.

3

Il bot può rispondere da documenti con versione?

Sì, se le pagine dei documenti con versione sono pubbliche e incluse nella scansione o nella mappa del sito.

4

Può identificare lacune nella documentazione?

Su Pro o Business, le domande segnalate sono indicatori euristici di possibili lacune da approfondire, non diagnosi definitive dei contenuti MkDocs.