Funciona con páginas de Material for MkDocs
Indexa guías, páginas de referencia y HTML estático generado de sitios públicos de MkDocs o Material for MkDocs sin reemplazar el tema.
Un chatbot de IA para la documentación de MkDocs y Material for MkDocs. ChattyBox rastrea tu sitio público y puede enlazar las respuestas a páginas recuperadas. Comprueba la precisión de las respuestas y las citas. Sin canalización de indexación en Python ni RAG personalizado que mantener.
ChattyBox rastrea tu sitio web, documentación, centro de ayuda, CMS o base de conocimientos existentes. El contenido recuperado puede orientar las respuestas del chatbot; comprueba la precisión de las respuestas y las citas.
Rastrea el sitemap desplegado de MkDocs o las rutas estables y versionadas que soportas intencionalmente.
Prueba preguntas de producto, Python y API y abre cada cita antes de la instalación.
Para Material, configura theme.custom_dir y extiende base.html desde overrides/main.html conservando el bloque de scripts con super().
Verifica la búsqueda integrada, la navegación instantánea, los controles móviles, la CSP y cada versión publicada de mike.
Lanzamiento en tres pasos
Los equipos de MkDocs normalmente quieren compilaciones estáticas rápidas, navegación clara y contenido técnico legible. ChattyBox mantiene ese flujo de trabajo intacto mientras añade un asistente con citas de fuentes al sitio publicado.
Usa estos puntos de control para decidir si ChattyBox debe funcionar junto a tu plataforma de documentación, sustituir a otro asistente o permanecer aislado para las pruebas.
Indexa guías, páginas de referencia y HTML estático generado de sitios públicos de MkDocs o Material for MkDocs sin reemplazar el tema.
Señale ChattyBox a las rutas de versión sobre las que desea que los usuarios pregunten y luego pruebe si las respuestas citan los documentos estables, más recientes o heredados previstos.
Debido a que ChattyBox rastrea el sitio público, los equipos no necesitan agregar indexación vectorial a su proceso de compilación de MkDocs o scripts de CI.
En Pro o Business, revisa las preguntas marcadas como señales heurísticas de posibles ejemplos ausentes, pasos de instalación poco claros o páginas de solución de problemas obsoletas.
Material for MkDocs y el tema integrado de MkDocs admiten ambos la herencia de plantillas, pero deberían usar directorios personalizados separados. La ruta de Material siguiente conserva su bloque de scripts con super(), añade un cargador asíncrono y sobrevive a la navegación instantánea sin reemplazar el comportamiento de búsqueda.
Vuelve a comprobar los bloques de plantilla y el comportamiento de navegación instantánea tras las actualizaciones del tema, y vuelve a rastrear siempre que se mueva un alias de mike.
| Preocupación de MkDocs | Decisión de implementación | Verificación |
|---|---|---|
Preocupación de MkDocs Personalización de Material | Decisión de implementación Define theme.name como material y theme.custom_dir como overrides. Extiende base.html, sobrescribe el bloque scripts, llama a super() y luego añade el script del widget. | Verificación Compila y sirve el sitio, luego confirma que la búsqueda y la navegación de Material siguen funcionando. |
Preocupación de MkDocs MkDocs vanilla | Decisión de implementación Usa theme.name: mkdocs con un directorio custom_theme separado. Añade la plantilla personalizada equivalente custom_theme/main.html en lugar de copiar las plantillas de Material. | Verificación Ejecuta mkdocs serve y verifica la búsqueda, los enlaces de siguiente y anterior, y el widget en más de una página. |
Preocupación de MkDocs Carga asíncrona y duplicados | Decisión de implementación Conserva un único cargador en el bloque de scripts heredado, dale un ID estable y no añadas el mismo fragmento mediante extra_javascript u otro parcial. | Verificación Tras cargas completas y transiciones instantáneas de Material, confirma que document.querySelectorAll("#chattybox-widget").length es 1. |
Preocupación de MkDocs Política de Seguridad de Contenido | Decisión de implementación Permite chattybox.ai en script-src, el origen configurado de la API en connect-src, fonts.googleapis.com en style-src y fonts.gstatic.com en font-src. El widget actual inyecta su CSS de componente, de modo que un style-src estricto también necesita 'unsafe-inline' hasta que exista una compilación con nonce o con hoja de estilos externa. | Verificación Comprueba la consola del navegador y el panel de Network por si hay solicitudes de script, estilo, fuente, fetch o WebSocket bloqueadas. |
Preocupación de MkDocs Búsqueda, navegación instantánea y móvil | Decisión de implementación Conserva los scripts del tema con super() y mantén el lanzador lejos del diálogo de búsqueda, el cajón, la paginación y los controles de consentimiento. | Verificación Prueba la búsqueda con teclado, varios enlaces instantáneos y una ventana de 390 píxeles sin superposición ni desplazamiento horizontal. |
Preocupación de MkDocs versiones de mike | Decisión de implementación Elige deliberadamente rutas de versión estables, más recientes o explícitas. Vuelve a rastrear tras mover un alias y excluye las versiones no soportadas cuando las respuestas entre versiones puedan inducir a error a los usuarios. | Verificación Usa mike serve para probar el cambio de versión y confirma que las citas se resuelven dentro de la versión prevista. |
Preocupación de MkDocs Fallo del widget o de las citas | Decisión de implementación Comprueba la indentación de YAML, el custom_dir activo, el nombre del bloque heredado, la clave de API, la CSP, el contenido del sitemap y si la compilación desplegada incluye la plantilla personalizada. | Verificación Inspecciona el HTML generado y prueba el artefacto de producción en lugar de depender solo de la recarga en vivo. |
Usa una pregunta del tema con una regla de plantilla verificable, luego abre la cita y confirma que coincide con la versión que seleccionó tu visitante.
Lista de verificación práctica para evaluar chatbots de IA para documentaciónPara Material for MkDocs, define theme.custom_dir como overrides, extiende base.html en overrides/main.html y llama a super() antes del script asíncrono del widget. MkDocs estándar necesita su propio directorio de tema personalizado y una plantilla main.html equivalente.
{% 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="https://adorable-woodpecker-629.convex.site/chat"
data-chattybox-widget="true"
></script>
{% endblock %}Sí. ChattyBox puede rastrear páginas públicas de MkDocs y Material for MkDocs e integrarse como un widget web estándar.
No. Añade el fragmento del widget a la plantilla del sitio o a una personalización del tema después de configurar el chatbot.
Sí, si las páginas de documentos versionados son públicas y están incluidas en el rastreo o en el mapa del sitio.
En Pro o Business, las preguntas marcadas son señales heurísticas para investigar posibles lagunas, no diagnósticos definitivos de tu contenido de MkDocs.