Añade un agente de voz con IA a un sitio de VitePress (2026)

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

VitePress tiene una opción head en su configuración del sitio que acepta una lista de etiquetas. Añade allí el script de AnveVoice, con async activado, y vuelve a compilar. La etiqueta se escribe en el HTML de cada página, y también puedes añadirla a páginas concretas mediante front matter. Pasos comprobados con la documentación oficial el 2026-10-14.

En resumen

• Dónde va el código: El array head en .vitepress/config.ts (o .js / .mts)
• Programación necesaria: Unas pocas líneas en el archivo de configuración
• Límites del plan: Ninguno por parte de VitePress. El plan Free de AnveVoice es suficiente
• Tiempo: Unos 2 minutos más una compilación

La opción head

La referencia de configuración del sitio de VitePress define head como un array de etiquetas, cada una escrita como una tupla: el nombre de la etiqueta, un objeto de atributos y, opcionalmente, el contenido interno. Su propio ejemplo para un script externo es una tupla con el nombre de la etiqueta script y un objeto que contiene async y src. Ese es el patrón que hay que seguir para AnveVoice. La guía de primeros pasos explica que el directorio .vitepress es una ubicación reservada para el archivo de configuración, y que puede ser JavaScript o TypeScript según cómo lo creó el asistente de configuración. Tu carpeta de contenido, a menudo docs, está junto a él; en un proyecto típico, la carpeta .vitepress está dentro de esa carpeta.

• 1. Obtén tu ID de incrustación — Crea un bot en app.anvevoice.app, copia el ID de incrustación y úsalo en lugar de YOUR_EMBED_ID. Puedes añadir &position=bottom-left o &theme=dark. <script src="https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID" async></script>

Método 1: para todo el sitio, en la configuración del sitio

• 1. Abre .vitepress/config.ts — Usa config.js o config.mts si es lo que tiene tu proyecto. Conserva tu title, description, themeConfig y el resto de ajustes.
• 2. Añade una entrada head — Dentro de defineConfig, añade el array. Si ya existe un array head, añade una línea nueva en él. import { defineConfig } from 'vitepress' export default defineConfig({ // ...title, description, themeConfig head: [ ['script', { async: '', src: 'https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID' }] ] })
• 3. Ejecuta o compila — npm run docs:dev inicia el servidor de desarrollo. npm run docs:build escribe el sitio estático en .vitepress/dist, la salida por defecto que indica la guía.

Método 2: una página o una sección

La referencia de front matter enumera una opción head que añade etiquetas extra para la página actual, combinadas con las del sitio. Úsala cuando solo una página de precios o de soporte necesita el agente de voz. Ponla al principio de ese archivo Markdown. Como VitePress navega entre páginas sin recargar el documento, una etiqueta que existe solo en una página puede seguir cargada después de que el visitante pase a otra. En la práctica, trata una etiqueta por página como una de todo el sitio, o verifica el comportamiento en tu compilación.

• 1. Añade el front matter — Cada etiqueta es una lista YAML anidada: el nombre y después sus atributos. --- head: - - script - async: '' src: https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID ---

Cómo se combinan las entradas, y transformHead

La referencia indica que las entradas head de la configuración del sitio, la configuración de idioma, la configuración de directorio, el front matter y el hook transformHead se combinan en ese orden, y que una entrada posterior sustituye a una anterior con la misma clave en lugar de añadirse. Si das a tu etiqueta un atributo id, la misma clave en un idioma o página puede sobrescribirla. Sin conflictos, no se sustituye nada. transformHead es un hook de compilación para etiquetas que no se pueden escribir de forma estática, por ejemplo un script que depende de la página. Los documentos indican que solo se ejecuta durante una compilación, no en desarrollo, y que sus etiquetas no se actualizan durante la navegación del lado del cliente. Para la URL fija de AnveVoice, el array head estático encaja mejor.

Particularidades de VitePress

• VitePress prerenderiza las páginas a HTML y luego las hidrata como una single-page app. El array head se incorpora al HTML de cada página durante la compilación.
• El servidor de desarrollo y la compilación respetan ambos el array head estático, así que verás el botón de voz mientras escribes la documentación. Protégelo con una comprobación en tiempo de compilación si no lo quieres.
• El sitio de documentación muestra actualmente 2.0 alpha en su menú de versiones, con 1.x como versión anterior. La opción head está documentada en la página de referencia actual; si usas 1.x, consulta esa página para tu versión.
• La guía de primeros pasos actual requiere Node.js 22 o posterior.
• Sirve la salida de .vitepress/dist por HTTPS. Los navegadores bloquean el acceso al micrófono en HTTP simple.

Comprueba que funciona

• 1. Compila — Ejecuta npm run docs:build y después npm run docs:preview si tu proyecto lo define, o abre la carpeta dist desde cualquier servidor estático.
• 2. Inspecciona el HTML — Abre .vitepress/dist/index.html y busca anvevoice.app en el head.
• 3. Úsalo en una página en vivo — En una ventana privada, carga el sitio desplegado, haz clic en el botón redondo del micrófono de abajo a la derecha y permite el micrófono.

Problemas comunes

• head no tiene efecto: lo pusiste dentro de themeConfig. Es una clave de nivel superior de la configuración del sitio.
• async no tiene efecto: confirma que el objeto de atributos es el segundo elemento de la tupla, como en el ejemplo, y que el código fuente muestra async en el script.
• Etiqueta duplicada por página: el mismo script está en la configuración y en una página. Elimina una.
• Contenido antiguo tras desplegar: purga la caché del CDN o del host y recarga sin caché.

Fuentes

• Docs de VitePress: configuración del sitio (head, transformHead) (https://vitepress.dev/reference/site-config) — consultado el 2026-10-14
• Docs de VitePress: configuración en front matter (head) (https://vitepress.dev/reference/frontmatter-config) — consultado el 2026-10-14
• Docs de VitePress: primeros pasos (ubicación de la configuración, salida de compilación) (https://vitepress.dev/guide/getting-started) — consultado el 2026-10-14

Relacionado

• Cómo añadir AnveVoice a un sitio de Docusaurus
• 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.