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

Cómo añadir AnveVoice a un sitio de documentación con MkDocs

MkDocs genera HTML sencillo, así que la etiqueta va en una plantilla del tema. Apunta theme.custom_dir a una carpeta de sustituciones, añade un main.html que extienda base.html y coloca el script en el bloque scripts. Recompila y despliega, y el botón de voz aparecerá en todas las páginas de la documentación. Pasos comprobados con la documentación oficial el 2026-10-14.

En resumen

• Dónde va el código: overrides/main.html (o custom_theme/main.html) en el bloque scripts, definido con theme.custom_dir en mkdocs.yml
• Programación necesaria: Una línea de YAML y una plantilla Jinja corta; sin plugin
• Límites del plan: Ninguno por parte de MkDocs; es software de código abierto que alojas tú (GitHub Pages, Netlify, Cloudflare Pages, etc.)
• Tiempo: Unos 5 minutos, más tu compilación y despliegue habituales

Cómo decide MkDocs qué acaba en la página

MkDocs convierte Markdown en HTML estático renderizando cada página a través de un tema. El tema controla el marcado que la rodea: cabecera, navegación, pie y las etiquetas script de la parte inferior. Esto importa aquí, porque la etiqueta de AnveVoice es un elemento script, y el HTML sin procesar colocado dentro de un archivo Markdown solo aparece en esa única página. La documentación de MkDocs sobre personalizar el tema describe la vía admitida para añadidos en todo el sitio: define custom_dir bajo theme en mkdocs.yml, y cualquier archivo de esa carpeta con el mismo nombre que un archivo del tema padre lo reemplaza. Un archivo llamado main.html que extiende base.html te permite sustituir bloques concretos sin copiar todo el tema. El mismo mecanismo funciona con el popular tema Material for MkDocs, que documenta una carpeta overrides con su propio main.html. Además existe la opción extra_javascript en mkdocs.yml. La referencia de configuración la describe como una lista de archivos JavaScript de tu docs_dir que el tema incluye como etiquetas script, y admite una forma de mapa con path y una clave async opcional. Como la documentación la enfoca en archivos de docs_dir y no dice nada sobre direcciones externas, esta guía usa la sustitución de plantilla, que es la vía que la documentación del tema describe para cargar un script desde cualquier lugar.

• 1. Obtén tu etiqueta de instalación — Inicia sesión en app.anvevoice.app, crea el bot para tu sitio de documentación y copia el embed ID. Sustituye YOUR_EMBED_ID más abajo. Añade &position=bottom-left o &theme=dark a la URL si quieres mover el botón o adaptarlo a un tema oscuro de documentación. <script src="https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID" async></script>

Método 1: sustituir el bloque scripts con main.html

Esto funciona con los temas integrados mkdocs y readthedocs y con Material for MkDocs. El nombre de la carpeta es libre; los ejemplos usan overrides. En los temas Material y base, el bloque scripts está documentado como el lugar para el JavaScript que debe ejecutarse después del contenido de la página (se renderiza en la zona del pie). Si prefieres la etiqueta en el head, usa el bloque extrahead en su lugar; ambos aceptan la misma etiqueta.

• 1. Declara la carpeta de sustituciones — Abre mkdocs.yml y añade custom_dir bajo theme. Una ruta relativa se resuelve respecto a la carpeta que contiene mkdocs.yml. theme: name: material custom_dir: overrides
• 2. Crea overrides/main.html — Crea la carpeta junto a mkdocs.yml y añade main.html. Debe extender base.html. Llamar a super() conserva los scripts propios del tema, lo cual es importante: un bloque que solo contenga tu etiqueta reemplazaría por completo el bloque del padre. {% extends "base.html" %} {% block scripts %} {{ super() }} <script src="https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID" async></script> {% endblock %}
• 3. Recompila — Ejecuta mkdocs serve para previsualizar, o mkdocs build para generar la carpeta del sitio. Las sustituciones de plantillas se leen al compilar, así que reinicia el servidor de vista previa si la página no cambia.

Método 2: añadirlo solo a una página

Si quieres el agente de voz en una sola página, por ejemplo una guía de primeros pasos, puedes escribir el elemento script directamente en el archivo Markdown de esa página. MkDocs deja pasar el HTML sin procesar. Una sustitución de plantilla a nivel de sitio es más limpia para todo el conjunto de documentación, pero la vía en línea evita tocar el tema.

Notas de despliegue y caché para sitios de documentación

• Recuerda que la salida de MkDocs es estática. Editar main.html no cambia nada en tu sitio en vivo hasta que recompiles y vuelvas a desplegar (por ejemplo, con mkdocs gh-deploy o tu pipeline de CI).
• Navegación instantánea: Material for MkDocs puede cargar páginas sin recarga completa cuando navigation.instant está activado. El script de AnveVoice ignora una segunda copia en la página, así que una carga repetida es inofensiva, pero prueba la navegación entre páginas después de activar esa función.
• Búsqueda e impresión: el botón de voz es una superposición de la página; no altera el índice de búsqueda generado ni el resultado imprimible de tu contenido Markdown.
• HTTPS: los navegadores solo permiten el micrófono en páginas seguras, así que un sitio de documentación servido desde http:// mostrará el botón, pero no aparecerá la solicitud del micrófono. GitHub Pages y la mayoría de los alojamientos estáticos ofrecen HTTPS por defecto.

Comprueba que funciona

• 1. Inspecciona el HTML compilado — Tras mkdocs build, abre cualquier index.html generado en la carpeta del sitio y busca embed.js. La etiqueta debería aparecer una vez, cerca del final del body.
• 2. Abre la documentación desplegada — Visita el sitio en vivo en una ventana privada, busca el botón redondo del micrófono abajo a la derecha, haz clic en él, permite el micrófono y pregunta algo que tu documentación responda.

Problemas habituales

• La navegación o la búsqueda dejan de funcionar tras la sustitución: main.html reemplazó un bloque sin llamar a super(). Añade {{ super() }} como primera línea dentro del bloque.
• No cambia nada: custom_dir apunta a una carpeta incorrecta, o main.html no está directamente dentro de ella. La ruta es relativa a mkdocs.yml, no a docs/.
• La etiqueta aparece en un lugar inesperado: usaste el bloque head mientras el resto de scripts se cargan en el pie. Cualquiera de las dos posiciones funciona porque la etiqueta es asíncrona.
• El botón queda oculto tras un elemento del tema: el pie fijo o el banner de cookies del tema pueden solaparse en la zona inferior derecha. Añade &position=bottom-left a la URL de la etiqueta.

Fuentes

• MkDocs: personalizar tu tema (custom_dir, main.html, bloques) (https://www.mkdocs.org/user-guide/customizing-your-theme/) — consultado el 2026-10-14
• MkDocs: configuración (extra_javascript, custom_dir del tema) (https://www.mkdocs.org/user-guide/configuration/) — consultado el 2026-10-14
• Material for MkDocs: personalización (overrides, bloque scripts) (https://squidfunk.github.io/mkdocs-material/customization/) — consultado el 2026-10-14

Relacionado

• Cómo añadir AnveVoice a un sitio Hexo
• Cómo añadir AnveVoice a un sitio de Docusaurus
• Cómo añadir AnveVoice a un sitio de VitePress
• Cómo añadir AnveVoice a un sitio Hugo

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.