Saltar al contenido principal
Bot de soporte para MkDocs

Añade un chatbot de IA con citas de fuentes a tu documentación de MkDocs y Material

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.

Rastrea páginas de documentación publicadasRespuestas con citas de fuentesIncrustado con un scriptNo se requiere migración de documentosNo se requiere tarjeta de créditoTu contenido sigue siendo tuyo
Preguntar a ChattyBox
¿Por dónde debería empezar si necesito una respuesta fiable de este sitio?
Empieza añadiendo la URL pública de tu sitio a ChattyBox. Recupera contenido indexado para orientar las respuestas y puede mostrar enlaces a páginas fuente para que los visitantes las revisen. Prueba las respuestas y los mensajes de respaldo antes del lanzamiento.
iFuentes3^
MkDocs guía
chattybox.ai
Analítica
chattybox.ai
Inicio
chattybox.ai

Conversación ilustrativa: no es un chat en directo.

Con tecnología de ChattyBox

Lance un chatbot con citas de fuentes sin reconstruir su pila web

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.

La plantilla personalizada de Material conserva el JavaScript del tema y añade un único cargador asíncrono del widget.
MkDocs vanilla usa un directorio de tema personalizado separado en lugar de asumir las rutas de Material.
Las comprobaciones cubren la coexistencia de la búsqueda, la navegación instantánea, los cargadores duplicados y las ventanas de visualización móviles estrechas.
La selección de rastreo consciente de la versión mantiene deliberadas las rutas estables, más recientes y heredadas de mike.
Paso del flujo de trabajo

Rastrea el sitemap desplegado de MkDocs o las rutas estables y versionadas que soportas intencionalmente.

Paso del flujo de trabajo

Prueba preguntas de producto, Python y API y abre cada cita antes de la instalación.

Paso del flujo de trabajo

Para Material, configura theme.custom_dir y extiende base.html desde overrides/main.html conservando el bloque de scripts con super().

Paso del flujo de trabajo

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

Pegue la URL de MkDocs, pruebe las respuestas con citas y luego instale el widget.

Flujo de trabajo específico de MkDocs

Soporte conversacional para sitios de documentación estática de Python

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.

Camino de decisión

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.

01

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.

02

Manejar deliberadamente la documentación versionada

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.

03

No hay trabajo de indexación de Python que mantener

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.

04

Mejorar documentos a partir de preguntas reales.

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.

Evidencia editorial probada

Rutas de instalación probadas para Material y MkDocs vanilla

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.

Autor técnico
Equipo de documentación de ChattyBox
Revisor técnico
Ingeniería de ChattyBox
Última actualización
Información verificada
MkDocs, Material for MkDocs y mike

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.

Configuración de custom_dir de Material for MkDocs y personalización de la plantilla main que conserva los scripts del tema
Referencia de instalación original: theme.custom_dir selecciona la plantilla personalizada y super() mantiene intactos los scripts de búsqueda y navegación de Material.
Decisiones de instalación de Material y MkDocs vanilla con comprobaciones de extremo a extremo.
Preocupación de MkDocsDecisión de implementaciónVerificació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.
Comprobación de respuesta citada

Prueba una respuesta contra la versión activa

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ón
Pregunta a las guías de MkDocs
¿Cómo añado el widget sin romper la búsqueda de Material?
Define theme.custom_dir como overrides, crea overrides/main.html, extiende base.html y añade el cargador asíncrono dentro del bloque de scripts después de super(). Llamar a super() conserva los scripts que Material usa para la búsqueda y la navegación.

Conversación ilustrativa: no es un chat en directo.

Con tecnología de ChattyBox
Página móvil de Material for MkDocs con la búsqueda y ChattyBox visibles sin controles superpuestos
Referencia móvil original: la búsqueda sigue disponible, el lanzador tiene un objetivo táctil utilizable y la página no se desplaza horizontalmente.
Ruta de instalación

Cómo agregar el widget a MkDocs

Para 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.

  1. 1Cree un proyecto ChattyBox e ingrese la URL o el mapa del sitio de su sitio MkDocs o Material for MkDocs.
  2. 2Pruebe preguntas reales de MkDocs en el panel y confirme que las citas apunten a las páginas correctas.
  3. 3Añade la plantilla personalizada probada, compila el sitio y verifica la búsqueda, la navegación, la CSP y el comportamiento en móvil.
overrides/main.html
html
{% 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 %}
Preguntas frecuentes

Preguntas comunes

1

¿ChattyBox funciona con Material for MkDocs?

Sí. ChattyBox puede rastrear páginas públicas de MkDocs y Material for MkDocs e integrarse como un widget web estándar.

2

¿Necesito cambiar mi canal de compilación de Python?

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.

3

¿Puede el bot responder desde documentos versionados?

Sí, si las páginas de documentos versionados son públicas y están incluidas en el rastreo o en el mapa del sitio.

4

¿Puede identificar lagunas en la documentación?

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.