Chatbot de IA con fuentes para Docusaurus 3
Docusaurus se comporta como una aplicación de una sola página después de la primera carga. Una integración de widget que solo funciona en el documento inicial, o que añade un segundo cargador en cada cambio de ruta, no está lista para producción. Esta guía utiliza una identidad estable para el script y una raíz del tema que permanece montada en todas las rutas de documentación.
Autor y revisor técnico: Michael Fisher, responsable de ChattyBox. Publicado y revisado técnicamente el 10 de julio de 2026. Las comprobaciones reproducibles que se indican a continuación son un tutorial de implementación, no una evaluación de rendimiento ni de precisión.
1. Añade el componente de tema Root
Crea src/theme/Root.tsx en tu sitio de 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}</>;
}
El ID estable chattybox-widget es la parte importante. React Strict Mode puede volver a montar los efectos durante el desarrollo, y Docusaurus cambia las rutas sin reemplazar el documento. Esta protección hace que ambos casos sean idempotentes.
Usa la URL de API que muestra tu proyecto de ChattyBox en lugar de copiar una implementación de ejemplo. Consulta la referencia de instalación del widget para conocer los atributos actuales y la guía de producto de Docusaurus para obtener orientación sobre la selección de fuentes y la evaluación.
2. Mantén el cargador montado
No coloques este script dentro de una página de documentación individual ni de un layout que Docusaurus reemplace durante la navegación. El componente Root personalizado mediante swizzling envuelve la aplicación durante toda su vida útil, por lo que el widget sigue disponible mientras los visitantes pasan de una guía a otra y consultan las referencias.
Si tu sitio ya tiene src/theme/Root.tsx, combina el efecto con el componente existente en lugar de reemplazar los proveedores de autenticación, analítica u otros.
3. Ten en cuenta la política de seguridad de contenido
Una política restrictiva debe permitir:
https://chattybox.aienscript-srcpara el cargador del widget.- El origen de la API de chat que hayas configurado en
connect-src. https://fonts.googleapis.comenstyle-srcyhttps://fonts.gstatic.comenfont-srcsi la fuente del widget aún no está disponible.- Estilos de componentes en línea en
style-srcpara la compilación actual del widget.
Parte de la política existente y añade únicamente los orígenes que realmente utilices. No sustituyas una política restrictiva por un comodín amplio.
4. Reproduce las comprobaciones de integración
En tu proyecto de Docusaurus, añade el wrapper Root anterior y ejecuta:
bun install
bun run start
Después, verifica lo siguiente:
- Abre dos rutas de documentación diferentes sin actualizar completamente el navegador.
- Ejecuta
document.querySelectorAll('#chattybox-widget').lengthdespués de cada navegación. Debe seguir siendo1. - Haz una pregunta cuya respuesta esté en una página indexada y confirma que la respuesta enlaza con esa página.
- Haz una pregunta sin soporte y confirma que el asistente ofrece una respuesta alternativa en lugar de inventar una fuente.
- Prueba el lanzador en una ventana móvil estrecha y comprueba que no cubra los controles de navegación ni de paginación.
La comprobación del recuento de scripts demuestra que se evitan los duplicados. No demuestra la calidad de la recuperación. Utiliza un conjunto representativo de preguntas y la guía de scraping para validar la cobertura de fuentes antes del lanzamiento.
Qué supervisar tras el lanzamiento
Registra las preguntas no resueltas, las citas incorrectas, las páginas de fuentes obsoletas y las rutas en las que el lanzador oculta controles del sitio. Vuelve a probar después de actualizar el tema de Docusaurus, porque los cambios en la navegación y el diseño del contenido pueden afectar a la ubicación aunque el cargador siga funcionando correctamente.
Para una secuencia de despliegue más amplia, utiliza la lista de comprobación para implementar un chatbot de documentación y la lista de comprobación de lanzamiento.