Añade un chatbot de IA con citas a MkDocs

Los temas de MkDocs exponen distintos directorios de sobrescritura, y Material puede navegar entre páginas sin una recarga completa. Una integración duradera debe conservar los scripts existentes del tema, cargar el widget una sola vez y coexistir con la búsqueda y la navegación en dispositivos móviles.

Autor y revisor técnico: Michael Fisher, responsable de ChattyBox. Publicado y revisado técnicamente el 10 de julio de 2026. El protocolo de verificación siguiente es un tutorial de implementación; no se afirma ningún resultado de tráfico, desvío de consultas ni precisión de las respuestas.

1. Elige el directorio de sobrescritura correcto

Para Material for MkDocs, apunta custom_dir a un directorio overrides:

site_name: My documentation
theme:
  name: material
  custom_dir: overrides
  features:
    - navigation.instant

Para el tema integrado, utiliza un directorio de tema personalizado independiente:

site_name: My documentation
theme:
  name: mkdocs
  custom_dir: custom_theme

Mantener las variantes separadas deja claro qué plantilla base upstream se está ampliando.

2. Amplía el bloque de scripts

Crea overrides/main.html para Material o custom_theme/main.html para el tema integrado:

{% extends "base.html" %}

{% block scripts %}
  {{ super() }}
  <script
    id="chattybox-widget"
    src="https://chattybox.ai/widget.js"
    async
    data-api-key="YOUR_API_KEY"
    data-api-url="YOUR_CHAT_API_URL"
    data-chattybox-widget="true"
  ></script>
{% endblock %}

{{ super() }} conserva los scripts proporcionados por el tema, incluidos los comportamientos de navegación y búsqueda. Omitirlo puede hacer que el widget parezca funcionar mientras rompe silenciosamente la interfaz de documentación. El ID estable también te proporciona una comprobación directa de cargadores duplicados.

Utiliza valores específicos del proyecto de la referencia de instalación del widget. La guía del chatbot de IA para MkDocs explica el alcance de las fuentes, el comportamiento del rastreo y las preguntas que debes evaluar antes de publicar.

3. Compila las dos variantes

Desde tu proyecto de MkDocs:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

cd material
mkdocs build --strict

cd ../vanilla
mkdocs build --strict

--strict convierte las advertencias en errores, lo que permite detectar problemas de navegación y configuración antes de evaluar el widget.

4. Ejecuta las comprobaciones en el navegador

Sirve cada variante y verifica lo siguiente:

1. La búsqueda integrada sigue abriéndose y devuelve el resultado de documentación esperado.
2. La navegación instantánea de Material cambia de ruta sin duplicar el cargador del widget.
3. document.querySelectorAll('#chattybox-widget').length sigue siendo 1 después de varios cambios de ruta.
4. En una ventana de 390 px, el lanzador no cubre la búsqueda, la navegación ni los controles de anterior/siguiente.
5. Una pregunta con soporte cita la página esperada y una pregunta sin soporte produce una respuesta alternativa prudente.

Las cuatro primeras comprobaciones validan el comportamiento de la integración. La quinta depende de las páginas que indexes y requiere un conjunto de evaluación representativo; sigue la guía de scraping y la lista de comprobación de lanzamiento en lugar de considerar que una carga correcta del script demuestra la calidad de las respuestas.

5. Conserva una CSP restrictiva

Permite el host del widget en script-src, el origen de la API configurada en connect-src y los orígenes de las fuentes en style-src y font-src cuando sea necesario. El widget actual inyecta estilos de componentes, por lo que una política estricta también necesita una estrategia explícita para los estilos en línea. Evita las listas de orígenes comodín.

Lista de comprobación de mantenimiento

Vuelve a compilar las dos variantes del tema después de actualizar MkDocs o Material, porque los nombres de los bloques de las plantillas upstream pueden cambiar. Mantén estable el ID del script, conserva super() y repite las comprobaciones de búsqueda, navegación instantánea, solapamiento en móviles y citas de fuentes.

Para planificar un despliegue de principio a fin, utiliza la lista de comprobación para implementar un chatbot de documentación.

Fuentes

• Referencia de instalación del widget de ChattyBox
• Personalización de temas de MkDocs
• Personalización de Material for MkDocs
• Guía de políticas de seguridad de contenido de MDN