Docusaurus

Sincronizza il tuo sito di documentazione Docusaurus nella base di conoscenza di AI SmartTalk. La tua AI apprenderà da ogni pagina nel tuo sitemap—perfetto per i bot di supporto che rispondono a domande tecniche.

---

Panoramica

L'integrazione di Docusaurus ti consente di:

• Importare automaticamente tutte le pagine dal tuo sitemap
• Mantenere i documenti sincronizzati quando pubblichi aggiornamenti
• Rispondere a domande sulla tua documentazione in modo conversazionale
• Ridurre il carico di supporto lasciando che l'AI gestisca domande comuni

Curiosità: La documentazione di AI SmartTalk utilizza Docusaurus, e questa integrazione alimenta il nostro chatbot di supporto!

---

Requisiti

Prima di iniziare, assicurati di avere:

• Un account attivo di AI SmartTalk
• Un sito Docusaurus con un valido sitemap.xml
• Il tuo sito deve essere accessibile pubblicamente (o fornire autenticazione)

---

Procedura Passo-Passo

Passo 1: Trova il Tuo Sitemap

Docusaurus genera automaticamente un sitemap. Trovalo qui:

https://your-docs-site.com/sitemap.xml

Verifica che si carichi nel tuo browser e contenga le tue pagine di documentazione.

Passo 2: Aggiungi l'Integrazione Docusaurus

1. Accedi al tuo account AI SmartTalk
2. Naviga su Impostazioni → Integrazioni
3. Trova Docusaurus e clicca su Collega
4. Inserisci l'URL del tuo sitemap
5. Clicca su Convalida

Passo 3: Configura le Impostazioni di Importazione

Dopo la convalida, configura il tuo import:

Impostazione	Descrizione
URL del Sitemap	URL completo al tuo sitemap.xml
Modelli inclusi	Sincronizza solo le pagine che corrispondono ai modelli (opzionale)
Modelli esclusi	Salta pagine o sezioni specifiche (opzionale)

Passo 4: Avvia l'Importazione

1. Clicca su Importa Pagine
2. AI SmartTalk esplora ogni URL nel tuo sitemap
3. Il contenuto viene estratto e aggiunto alla tua base di conoscenza
4. Attendi il completamento dell'importazione (progresso mostrato)

Passo 5: Verifica l'Importazione

1. Vai su Conoscenza in AI SmartTalk
2. Le tue pagine di documentazione dovrebbero apparire
3. Metti alla prova la tua AI ponendo domande sui tuoi documenti

---

Cosa Viene Sincronizzato

Contenuto	Come Viene Elaborato
Titolo della pagina	Utilizzato come identificatore del documento
Contenuto della pagina	Testo completo estratto da HTML
Intestazioni	Conservate per la struttura
Blocchi di codice	Inclusi così come sono
Tabelle	Convertite in formato leggibile
URL	URL della pagina memorizzato per riferimento

Estrazione dei Contenuti

AI SmartTalk estrae l'area principale del contenuto e ignora:

• Menu di navigazione
• Barre laterali
• Piè di pagina
• Script e stili

---

Comportamento di Sincronizzazione

Importazione Manuale

Clicca su Importa nelle impostazioni di integrazione per:

• Recuperare l'ultimo sitemap
• Aggiungere nuove pagine
• Aggiornare pagine modificate
• Rimuovere pagine eliminate

Mantenere i Documenti Aggiornati

Per una documentazione sempre attuale:

1. Aggiornamento manuale: Clicca su Importa dopo aver pubblicato aggiornamenti
2. Sincronizzazione programmata: Usa SmartFlow per automatizzare le importazioni

Importazione Programmata SmartFlow

Workflow: Docusaurus Auto-Sync
Trigger: Programmato (Giornaliero alle 3:00 AM)
Actions:
  - Sync Connector:
      Type: Docusaurus
      Sitemap: https://docs.example.com/sitemap.xml

---

Modelli URL

Modelli Inclusi

Sincronizza solo sezioni specifiche:

Modello	Effetto
/docs/api/*	Solo documentazione API
/docs/guides/*	Solo sezione guide
/blog/*	Solo post del blog

Modelli Esclusi

Salta determinate pagine:

Modello	Effetto
/docs/internal/*	Salta documenti interni
/changelog	Salta pagina changelog
*/draft-*	Salta pagine bozza

---

Casi d'Uso

Bot di Supporto Tecnico

Sincronizza la documentazione del tuo prodotto:

• "Come installo l'SDK?"
• "Quali sono i limiti di frequenza dell'API?"
• "Mostrami un esempio di autenticazione"

Documentazione per Sviluppatori

Sincronizza riferimenti e guide API:

• "Quali parametri accetta l'endpoint /users?"
• "Come gestisco i webhook?"
• "Qual è la differenza tra l'API v1 e v2?"

Base di Conoscenza Interna

Sincronizza wiki aziendali e procedure:

• "Qual è il processo per richiedere il PTO?"
• "Come configuro il mio ambiente di sviluppo?"
• "Dove trovo le linee guida del marchio?"

---

Risoluzione dei Problemi

Problemi con il Sitemap

Problema	Soluzione
"Sitemap non valido"	Verifica che l'URL restituisca XML valido
"Nessuna pagina trovata"	Controlla che il sitemap contenga voci <url>
"Accesso negato"	Assicurati che il sitemap sia accessibile pubblicamente

Problemi di Importazione

Problema	Soluzione
Pagine mancanti	Controlla i modelli inclusi/esclusi
Importazione bloccata	Siti grandi richiedono tempo; attendi o importa in batch
Contenuto obsoleto	Ri-importa per recuperare le versioni più recenti

Qualità del Contenuto

Problema	Soluzione
Contenuto errato estratto	Segnala il problema—potrebbe essere necessaria un'estrazione personalizzata
Blocchi di codice mancanti	Verifica che il codice sia nei tag standard <pre><code>
Testo illeggibile	Controlla la codifica della pagina (UTF-8 consigliato)

---

Gestione dell'Integrazione

Azione	Come
Ri-importa tutto	Clicca su Importa nelle impostazioni di integrazione
Cambia sitemap	Aggiorna l'URL e ri-importa
Rimuovi contenuto	Disconnetti l'integrazione o elimina dalla Conoscenza
Disconnetti	Impostazioni → Integrazioni → Docusaurus → Disconnetti

---

Migliori Pratiche

1. Contenuto di qualità: Documenti ben scritti = migliori risposte dell'AI
2. Struttura chiara: Usa intestazioni, elenchi e tabelle
3. Titoli descrittivi: I titoli delle pagine aiutano l'AI a comprendere il contesto
4. Sincronizzazioni regolari: Mantieni l'AI aggiornata con la documentazione più recente
5. Testa a fondo: Fai domande comuni per verificare l'accuratezza dell'AI

---

Suggerimenti per la Configurazione di Docusaurus

Ottimizza per l'Estrazione dell'AI

Nel tuo docusaurus.config.js:

module.exports = {
  // Assicurati che il sitemap venga generato
  plugins: ['@docusaurus/plugin-sitemap'],
  
  // Usa titoli di pagina descrittivi
  title: 'Documentazione del Tuo Prodotto',
  
  // Includi metadati
  themeConfig: {
    metadata: [{
      name: 'description',
      content: 'Documentazione per il Tuo Prodotto'
    }],
  },
};

Escludi Pagine dal Sitemap

Per impedire che determinate pagine vengano sincronizzate:

// Nella frontmatter della pagina
---
title: Pagina Interna
sitemap:
  exclude: true
---

---

Documentazione Correlata

• Panoramica delle Integrazioni
• Gestione della Base di Conoscenza
• Integrazione RSS Feed — Per contenuti di blog/notizie
• Trigger Programmati di SmartFlow — Automatizza le importazioni