yoursite.com/docs utilizando Cloudflare, debes crear y configurar un Cloudflare Worker.
Antes de comenzar, necesitas una cuenta de Cloudflare y un nombre de dominio (puede gestionarse dentro o fuera de Cloudflare).
Configura tu ruta base
- Ve a la página de configuración de dominio personalizado en tu dashboard.
- Habilita el interruptor Host at e ingresa tu ruta base. Por ejemplo,
/docso/help. - Ingresa tu dominio.
- Ingresa tu ruta base.
- Haz clic en Add domain.
Configura un Worker
Proxies con implementaciones de Vercel
Lista obligatoria de rutas permitidas
/.well-known/acme-challenge/*- Obligatoria para la verificación de certificados de Let’s Encrypt/.well-known/vercel/*- Obligatoria para la verificación del dominio de Vercel
Requisitos para el reenvío de cabeceras
Host con el destino <subdomain>.mintlify.site, como se muestra en el script de ejemplo, en lugar de pasar el encabezado Host original de la solicitud. Encabezados Host incorrectos provocan que las solicitudes de verificación fallen.
Configurar el enrutamiento
Después de desplegar tus cambios, tu documentación suele estar disponible en tu subruta en unos minutos. Si tu configuración incluye cambios de DNS, la propagación puede tardar entre 1 y 4 horas y, en casos excepcionales, hasta 48 horas. Si tu documentación no está disponible de inmediato, espera antes de intentar solucionar el problema.
Prueba tu Worker
- Prueba usando la URL de vista previa del Worker:
your-worker.your-subdomain.workers.dev/docs - Verifica que el Worker dirija a tu documentación de Mintlify y a tu sitio web.
Agregar dominio personalizado
- En tu dashboard de Cloudflare, ve a tu Worker.
- Ve a Settings > Domains & Routes > Add > Custom Domain.
- Agrega tu dominio.
Resolver conflictos de DNS
- Elimina el registro DNS existente para tu dominio. Consulta Eliminar registros DNS en la documentación de Cloudflare para obtener más información.
- Vuelve a tu Worker y agrega tu dominio personalizado.
Enrutamiento personalizado de Webflow
/docs en el mismo dominio, configura un enrutamiento personalizado mediante Cloudflare Workers. El Worker redirige mediante proxy todo el tráfico que no sea de docs hacia tu sitio principal.
- En Webflow, configura una landing page para tu sitio principal, por ejemplo
landing.yoursite.com. Esta es la página que verán los visitantes cuando entren a tu sitio. - Despliega tu sitio principal en la landing page. Esto garantiza que tu sitio principal siga siendo accesible mientras configuras el Worker.
- Para evitar conflictos, actualiza cualquier URL absoluta en tu sitio principal para que sea relativa.
- En Cloudflare, haz clic en Edit Code y añade el siguiente script en el código de tu Worker.
- Haz clic en Deploy y espera a que se propaguen los cambios.
Después de desplegar tus cambios, tu documentación suele estar disponible en tu subruta en unos minutos. Si tu configuración incluye cambios de DNS, la propagación puede tardar entre 1 y 4 horas y, en casos excepcionales, hasta 48 horas. Si tu documentación no está disponible de inmediato, espera antes de intentar solucionar el problema.
Solución de problemas de bloqueo del firewall
Síntomas
- La página de documentación carga inicialmente pero se bloquea con un error 500 después de 30-60 segundos.
- Navegación del lado del cliente lenta o interrumpida entre páginas.
- Errores 403 en la consola del navegador en solicitudes a las rutas
/mintlify-assets/*. - Mensajes de desafíos de seguridad de Cloudflare sobre “datos malformados” o “patrones de URL sospechosos”.
Causa raíz
- Múltiples símbolos
%en parámetros de URL codificados. - Cadenas de consulta largas con caracteres especiales.
- Solicitudes automatizadas desde pestañas inactivas.
Solución
Crear la excepción del firewall
- Inicia sesión en tu dashboard de Cloudflare.
- Selecciona tu dominio.
- Ve a Security > WAF.
- Haz clic en Create rule.
- Configura la regla con estos ajustes:
- Campo:
Hostname - Operador:
equals - Valor:
docs.yourdomain.com(reemplaza con tu dominio real de documentación)
- Campo:
URI Path - Operador:
starts with - Valor:
/mintlify-assets/
- Acción:
Skip - Selecciona:
All remaining custom rules,Managed rulesySuper Bot Fight Mode
- Activa Log para rastrear las solicitudes coincidentes.
- Haz clic en Deploy.
Verifica la regla
- Abre tu sitio de documentación en un navegador.
- Deja la página inactiva durante 2-3 minutos.
- Navega entre páginas.
- Revisa la consola del navegador en busca de errores 403.
- Asegúrate de que el hostname coincida exactamente con tu dominio de docs.
- Confirma que la ruta URI use
starts with(nocontains). - No incluyas comodines (
*) en el valor de la ruta. - Verifica que hayas habilitado y desplegado la regla.
Errores comunes
- Usar el operador
containscon/mintlify-assets/*. El*se interpreta como un carácter literal, no como un comodín. - Usar
equalspara la ruta URI. Esto solo coincide con la ruta exacta/mintlify-assets/y no con subrutas. - Olvidar excluir Bot Fight Mode. Inclúyelo explícitamente en la acción de exclusión.
- Configurar un nombre de host incorrecto. Debe coincidir con tu dominio de documentación real.
Solución de problemas adicional
- Revisa el registro de Security > Events de Cloudflare para detectar solicitudes bloqueadas.
- Verifica que tu Cloudflare Worker (si usas una subruta personalizada) establezca el encabezado
Hostcon tu destino<subdomain>.mintlify.siteen lugar de pasar el encabezadoHostoriginal de la solicitud. - Configura temporalmente el nivel de seguridad en “Essentially Off” para confirmar que Cloudflare es la causa.
- Revisa cualquier Page Rule personalizada que pueda anular la excepción del firewall.