Saltar al contenido principal
ChattyBoxEmpieza gratis

Chatbot de IA con fuentes para Docusaurus 3

· 5 minutos de lectura
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

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 protege esta inserción concreta frente a los remontajes de React durante el desarrollo y los cambios de ruta del lado del cliente. No detecta otro cargador con un ID distinto o sin ID; utiliza una sola integración por página.

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.ai en script-src para el cargador del widget.
  • El origen de la API de chat que hayas configurado en connect-src.
  • Para el cargador del código fuente actual, https://fonts.googleapis.com en style-src y https://fonts.gstatic.com en font-src cuando inyecta la hoja de estilos de Inter. Un enlace coincidente a una hoja de estilos de Google Fonts impide esa inyección; que la fuente esté disponible por otro medio no basta. Verifica el comportamiento del cargador desplegado.
  • El origen de cualquier imagen de icono personalizado configurada en img-src.
  • Estilos de componentes en línea en style-src para 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:

  1. Abre dos rutas de documentación diferentes sin actualizar completamente el navegador.
  2. Ejecuta document.querySelectorAll('#chattybox-widget').length después de cada navegación. Debe seguir siendo 1.
  3. Haz una pregunta cuya respuesta esté en una página indexada y confirma que la respuesta enlaza con esa página.
  4. Haz preguntas sin soporte y evalúa si el asistente ofrece una respuesta alternativa en lugar de inventar una fuente; repite la prueba con casos representativos sin asumir que se abstendrá en todas las respuestas.
  5. 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 solo cuenta ese ID; aún puede existir otro cargador sin ID o con uno distinto. Revisa también todas las integraciones y el widget renderizado. El recuento 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.

Fuentes​