Añade un agente de voz con IA a un sitio de Docusaurus

Cómo añadir AnveVoice a un sitio de Docusaurus

Docusaurus tiene una opción diseñada para esto. Añade la URL de AnveVoice al array scripts de docusaurus.config.js (o .ts) con async en true y vuelve a compilar. Docusaurus inserta la etiqueta en el head de cada página que genera. Pasos comprobados con la documentación oficial el 2026-10-14.

En resumen

• Dónde va el código: El array scripts de docusaurus.config.js o docusaurus.config.ts
• Código necesario: Unas pocas líneas en el archivo de configuración; sin código React
• Límites del plan: Ninguno por parte de Docusaurus. El plan gratuito de AnveVoice es suficiente
• Tiempo: Unos 2 minutos más una compilación

El campo scripts

La referencia de configuración de Docusaurus define scripts como un array de scripts a cargar, donde cada valor es una cadena o un objeto con atributos. Las etiquetas se insertan en el head del HTML, y un objeto solo necesita un src más los atributos extra que quieras. La misma página advierte de que los scripts añadidos así bloquean el renderizado, y sugiere añadir async: true o defer: true a los objetos. La etiqueta de AnveVoice es asíncrona por diseño, así que usa la forma de objeto para mantener ese comportamiento. Es más sencillo que sustituir un componente del tema o sobrescribir la plantilla HTML, y sobrevive a las actualizaciones de Docusaurus, así que quédate con esta opción salvo que necesites algo condicional.

• 1. Obtén tu ID de incrustación — Crea un bot en app.anvevoice.app y copia el ID de incrustación del panel. La etiqueta que vas a reproducir tiene este aspecto. <script src="https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID" async></script>

Método 1: añadirlo a docusaurus.config

El archivo de configuración es docusaurus.config.js, o docusaurus.config.ts en un proyecto TypeScript, en la raíz del sitio junto a package.json. Docusaurus 3.x requiere Node.js 20 o posterior para compilar.

• 1. Abre el archivo de configuración — Localiza el objeto que exportas. Mantén tal cual tus title, url, presets y themeConfig existentes.
• 2. Añade la entrada scripts — Colócala en el nivel superior de la configuración exportada, junto a title y url. Si ya tienes un array scripts, añade este objeto en él. const config = { // ...title, url, baseUrl, presets, themeConfig scripts: [ { src: 'https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID', async: true, }, ], }; export default config;
• 3. Reinicia y compila — Reinicia npm run start para que la configuración se vuelva a cargar. Para producción, ejecuta npm run build; la guía de instalación indica que el sitio estático se escribe en la carpeta build.

Método 2: solo en compilaciones de producción

Como el archivo de configuración es JavaScript que se ejecuta en Node, puedes decidir en tiempo de compilación si incluir el script. Docusaurus ejecuta el servidor de desarrollo y la compilación de producción en entornos de Node distintos, así que una comprobación de NODE_ENV mantiene el botón de voz fuera de tu vista previa local de la documentación.

• 1. Haz la entrada condicional — Expande un array vacío cuando no estés en producción. scripts: [ ...(process.env.NODE_ENV === 'production' ? [{ src: 'https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID', async: true }] : []), ],

Navegación de página única

Docusaurus es una aplicación de página única. Su documentación de módulos de cliente señala que los scripts de módulo no se vuelven a ejecutar en las transiciones de página, y ofrece los hooks onRouteUpdate y onRouteDidUpdate para el código que debe ejecutarse en cada navegación. La etiqueta de AnveVoice no necesita esos hooks: el script se carga una vez con la primera página, y el botón permanece montado mientras los visitantes navegan por la documentación. No intentes volver a añadirla en cada ruta. La misma página indica que los módulos de cliente también se llaman durante el renderizado en el servidor, por lo que el código que solo funciona en el navegador necesita una protección. Otro motivo para preferir el campo scripts aquí: no necesita esa protección.

Particularidades de Docusaurus

• headTags es una opción relacionada, pero su documentación solo muestra un ejemplo con link, así que usa scripts para un script.
• Las versiones de la documentación, los locales de i18n y el blog comparten la misma configuración, así que una sola entrada los cubre todos.
• baseUrl no afecta a la etiqueta, porque la URL de AnveVoice es absoluta.
• Una Content Security Policy añadida por tu hosting o por un proxy inverso debe permitir https://anvevoice.app en script-src y connect-src.
• Los rastreadores de búsqueda y el cuadro de búsqueda de Algolia DocSearch no se ven afectados; el agente de voz es un widget adicional, no un sustituto de la búsqueda.

Comprueba que funciona

• 1. Compila y sirve en local — Ejecuta npm run build y sirve la carpeta build con npm run serve. Con el método 2, el script solo aparece en esta vista previa de estilo producción.
• 2. Busca en el resultado — Abre build/index.html y busca anvevoice.app dentro del head.
• 3. Abre una página de documentación y haz clic en el botón — Usa una ventana privada en el sitio HTTPS desplegado, haz clic en el botón redondo del micrófono de abajo a la derecha y permite el micrófono.

Problemas frecuentes

• Error de configuración tras editar: el array scripts está dentro de themeConfig. Debe ser una clave de primer nivel.
• Sin botón en npm run start: usas el método 2. Prueba con una compilación de producción.
• Sigue el comportamiento antiguo tras desplegar: tu hosting o CDN tiene en caché el HTML. Purga la caché y recarga con una recarga forzada.
• El botón parpadea o aparece tarde: un bloqueador de anuncios o una conexión lenta está retrasando el script. Es asíncrono, así que la documentación se renderiza primero.
• Dos botones: también añadiste la etiqueta en un archivo personalizado de src o de tema. Conserva solo la entrada de la configuración.

Fuentes

• Documentación de Docusaurus: docusaurus.config.js (scripts, headTags) (https://docusaurus.io/docs/api/docusaurus-config) — consultado el 2026-10-14
• Documentación de Docusaurus: arquitectura del cliente (módulos de cliente, hooks de ruta) (https://docusaurus.io/docs/advanced/client) — consultado el 2026-10-14
• Documentación de Docusaurus: instalación (versión de Node, carpeta build) (https://docusaurus.io/docs/installation) — consultado el 2026-10-14

Relacionado

• Cómo añadir AnveVoice a un sitio de VitePress
• Cómo añadir AnveVoice a un sitio de documentación con MkDocs
• Cómo añadir AnveVoice a un sitio Hugo
• Cómo añadir AnveVoice a un sitio web HTML sencillo

Prueba AnveVoice en tu sitio

Plan gratuito: 0 US$, 50.000 tokens al mes, sin tarjeta. Obtén tu ID de inserción en el panel y pega una etiqueta.