Cómo añadir el chatbot de IA Asyntai a Docusaurus

Guía paso a paso para sitios de documentación de Docusaurus

Plataforma:

Paso 1: Obtén su código de inserción

Primero, ve a tu Panel de control de Asyntai y desplázate hasta la sección "Código de inserción". Copia tu código de inserción único que se verá así:

<script async src="https://asyntai.com/static/js/chat-widget.js" data-asyntai-id="YOUR_WIDGET_ID"></script>

Nota: El código anterior es solo un ejemplo. Debe copiar su propio código de inserción único desde su Panel de control ya que contiene su ID de widget personal.

Paso 2: Añadir script a docusaurus.config.js (Recomendado)

La mejor forma de añadir el chatbot a todas las páginas de su sitio Docusaurus es a través del archivo de configuración:

Abra su proyecto Docusaurus en su editor de código
Localice y abra el archivo docusaurus.config.js en la raíz de su proyecto
Encuentra el objeto const config = { }
Añada o actualice el campo scripts con su widget de Asyntai:

const config = {
  // ... other config options

  scripts: [
    // Other scripts if any
    {
      src: 'https://asyntai.com/static/js/chat-widget.js',
      'data-asyntai-id': 'YOUR_WIDGET_ID',
      async: true,
    },
  ],

  // ... rest of config
};

Guarde el archivo docusaurus.config.js
Reconstruya su sitio ejecutando npm run build o yarn build
Reinicie el servidor de desarrollo si lo ejecuta localmente

Consejo: El campo scripts acepta un array de fuentes JavaScript. La etiqueta script se insertará en el head HTML de cada página automáticamente. Este es el método más limpio y fácil de mantener para sitios Docusaurus.

Método alternativo 1: Formato de cadena (Sintaxis más simple)

Si prefieres un enfoque más simple, puede usar formato de cadena en el array de scripts:

const config = {
  scripts: [
    'https://asyntai.com/static/js/chat-widget.js',
  ],
};

Nota: Al usar formato de cadena, necesitará modificar la URL del script para incluir su ID de widget como parámetro de consulta, o usar el formato de objeto mostrado en el Paso 2 que le permite establecer el atributo data-asyntai-id directamente.

Método alternativo 2: Etiquetas Head personalizadas

También puede añadir el script usando el campo headTags en docusaurus.config.js:

const config = {
  headTags: [
    {
      tagName: 'script',
      attributes: {
        src: 'https://asyntai.com/static/js/chat-widget.js',
        'data-asyntai-id': 'YOUR_WIDGET_ID',
        async: true,
      },
    },
  ],
};

Consejo: El campo headTags proporciona más control sobre las etiquetas HTML exactas insertadas en la sección <head>. Este método es funcionalmente equivalente a usar el campo scripts.

Método alternativo 3: Plantilla HTML personalizada (Avanzado)

Para usuarios avanzados que necesitan control completo sobre la plantilla HTML:

Cree un nuevo directorio: src/theme (si no existe)
Cree un archivo: src/theme/Root.js
Añada el siguiente código para inyectar el script dinámicamente:

import React, { useEffect } from 'react';

export default function Root({children}) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://asyntai.com/static/js/chat-widget.js';
    script.setAttribute('data-asyntai-id', 'YOUR_WIDGET_ID');
    script.async = true;
    document.head.appendChild(script);

    return () => {
      // Cleanup when component unmounts
      document.head.removeChild(script);
    };
  }, []);

  return <>{children}</>;
}

Guarde el archivo y reconstruya su sitio

Importante: El componente Root.js envuelve toda su aplicación. Este método avanzado solo debe usarse si necesita lógica JavaScript personalizada o tiene requisitos específicos que no pueden cumplirse con el enfoque del archivo de configuración.

Método alternativo 4: Personalizar el componente Footer

Puede personalizar el pie de página para incluir el script:

Ejecuta el comando swizzle: npm run swizzle @docusaurus/theme-classic Footer -- --eject
Esto crea una copia del componente Footer en src/theme/Footer/
Edita el componente Footer para incluir su etiqueta script
Añada el script antes de la etiqueta de cierre del pie de página
Guarde y reconstruya su sitio

Nota: El swizzling le da control total sobre los componentes de Docusaurus, pero significa que necesitará mantener ese componente usted mismo. Las actualizaciones de Docusaurus no actualizarán automáticamente los componentes modificados con swizzle.

Paso 3: Compilar y desplegar

Después de añadir el código, compile y despliegue su sitio Docusaurus:

# Build the site
npm run build

# Or with Yarn
yarn build

# Deploy to your hosting platform
# (Vercel, Netlify, GitHub Pages, etc.)

Consejo: Durante el desarrollo, ejecute npm start o yarn start para previsualizar sus cambios localmente. El chatbot debería aparecer en la esquina inferior derecha en todas las páginas.

Paso 4: Verificar la instalación

Después de desplegar sus cambios, abra su sitio de documentación en una nueva pestaña del navegador. Debería ver el botón del widget de chat en la esquina inferior derecha. Haga clic en él para asegurarse de que se abra y funcione correctamente.

¿No ves el widget? Asegúrese de haber reconstruido su sitio después de realizar cambios. Verifique que ha reemplazado YOUR_WIDGET_ID con su ID de widget real del panel de control. Limpie la caché de su navegador o visualice en modo incógnito. Abra la consola del navegador (F12) para verificar si hay errores de JavaScript.

Documentación