Skip to main content
Para alojar tu documentación en una subruta como yoursite.com/docs con AWS Route 53 y CloudFront, debes configurar tu proveedor de DNS para que apunte a tu distribución de CloudFront. Antes de configurar AWS, define tu ruta base en tu dashboard:
  1. Ve a la página de configuración de dominio personalizado en tu dashboard.
  2. Habilita el interruptor Host at e ingresa tu ruta base. Por ejemplo, /docs o /help.
  3. Ingresa tu dominio.
  4. Ingresa tu ruta base.
  5. Haz clic en Add domain.

​
Descripción general

Los siguientes ejemplos usan la ruta base /docs. Si utilizas otra ruta base, reemplaza /docs por la tuya.
Dirige el tráfico a estas rutas con una política de caché CachingDisabled:
  • /.well-known/acme-challenge/* - Obligatorio para la verificación de certificados de Let’s Encrypt
  • /.well-known/vercel/* - Obligatorio para la verificación del dominio
  • /docs/* - Obligatorio para el enrutamiento por subruta
  • /docs/ - Obligatorio para el enrutamiento por subruta
  • /_mintlify/* - Obligatorio para las solicitudes del playground de API
Dirige el tráfico a estas rutas con una política de caché CachingOptimized:
  • /mintlify-assets/* - Obligatorio para CSS, JavaScript y favicons
  • Default (*) - La página de inicio de tu sitio web
Todos los comportamientos (Behaviors) deben tener una origin request policy de AllViewerExceptHostHeader. Los comportamientos de tu subruta deben permitir todos los métodos HTTP. CloudFront solo permite solicitudes GET y HEAD de forma predeterminada, lo que bloquea las solicitudes POST que Mintlify usa para analíticas y otras funciones interactivas.

​
Crear una distribución de CloudFront

  1. Navega a CloudFront en la consola de AWS.
  2. Selecciona Create distribution.
  1. En Origin domain, ingresa [SUBDOMAIN].mintlify.site, donde [SUBDOMAIN] es el subdomain único de tu proyecto.
  1. En «Web Application Firewall (WAF)», habilita las protecciones de seguridad.
Las reglas de WAF pueden bloquear las solicitudes POST que Mintlify usa para analíticas y otras funciones interactivas. Si las analíticas dejan de aparecer en tu panel después de habilitar WAF, revisa los registros de WAF en busca de solicitudes bloqueadas a rutas bajo /docs/_mintlify/.
  1. Deja el resto de la configuración con los valores predeterminados.
  2. Selecciona Create distribution.

​
Agregar origen predeterminado

  1. Después de crear la distribución, ve a la pestaña “Origins”.
  1. Busca tu URL de staging que refleje el dominio principal. Esto varía según el proveedor de alojamiento de tu página de inicio. Por ejemplo, la URL de staging de Mintlify es mintlify-landing-page.vercel.app.
Si Webflow aloja tu página de inicio, usa la URL de staging de Webflow. Se verá como .webflow.io.Si usas Vercel, usa el domain .vercel.app disponible para cada proyecto.
  1. Crea un nuevo Origin y agrega tu URL de staging como el “Origin domain”.
Ahora deberías tener dos Origins: uno con [SUBDOMAIN].mintlify.site y otro con tu URL de staging.

​
Configurar comportamientos

Los comportamientos en CloudFront permiten controlar la lógica de subrutas. A grandes rasgos, queremos implementar la siguiente lógica:
  • Si un usuario llega a tu subruta personalizada, redirigir a [SUBDOMAIN].mintlify.site.
  • Si un usuario llega a cualquier otra página, redirigir a la página de inicio actual.
  1. Ve a la pestaña “Behaviors” de tu distribución de CloudFront.
  1. Selecciona el botón Create behavior y crea los siguientes comportamientos.

​
/.well-known/*

Crea comportamientos para las rutas de verificación de domain de Vercel con un Patrón de ruta de /.well-known/* y establece Origin and origin groups en la URL de tu documentación. Para “Cache policy”, selecciona CachingDisabled para garantizar que estas solicitudes de verificación se procesen sin caché.
Si .well-known/* es demasiado genérico, puedes acotarlo a un mínimo de 2 comportamientos para Vercel:
  • /.well-known/vercel/* - Obligatorio para la verificación de domain de Vercel
  • /.well-known/acme-challenge/* - Obligatorio para la verificación del certificado de Let’s Encrypt

​
Tu subruta

Crea un comportamiento con un Path pattern de la subruta que elijas, por ejemplo /docs, con Origin and origin groups apuntando a la URL .mintlify.site (en nuestro caso acme.mintlify.site).
  • Establece “Cache policy” en CachingDisabled.
  • Establece “Origin request policy” en AllViewerExceptHostHeader.
  • Establece “Viewer protocol policy” en Redirect HTTP to HTTPS.
  • Establece “Allowed HTTP methods” en GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
CloudFront solo permite solicitudes GET y HEAD de forma predeterminada. Si no permites todos los métodos HTTP, CloudFront rechaza las solicitudes POST que Mintlify usa para analíticas, y tu panel no mostrará ninguna vista de página aunque tu documentación se cargue normalmente.

​
Tu subruta con comodín

Crea un comportamiento con un Path pattern que sea la subruta que elijas seguida de /*, por ejemplo /docs/*, y con Origin and origin groups apuntando a la misma URL .mintlify.site. Esta configuración debe coincidir exactamente con el comportamiento de tu subruta base, con la excepción de Path pattern.
  • Establece “Cache policy” en CachingDisabled.
  • Establece “Origin request policy” en AllViewerExceptHostHeader.
  • Establece “Viewer protocol policy” en Redirect HTTP to HTTPS.
  • Establece “Allowed HTTP methods” en GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.

​
/mintlify-assets/*

Crea un comportamiento con un Path pattern de /mintlify-assets/* con Origin and origin groups apuntando a la URL .mintlify.site. Esta ruta sirve el CSS, JavaScript y favicons de tu documentación desde la raíz de tu dominio.
  • Establece “Cache policy” en CachingOptimized.
  • Establece “Origin request policy” en AllViewerExceptHostHeader.
  • Establece “Viewer protocol policy” en Redirect HTTP to HTTPS.

​
/_mintlify/*

Crea un comportamiento con un Path pattern de /_mintlify/* con Origin and origin groups apuntando a la URL .mintlify.site. Esta ruta gestiona las solicitudes del playground de API desde la raíz de tu dominio.
  • Establece “Cache policy” en CachingDisabled.
  • Establece “Origin request policy” en AllViewerExceptHostHeader.
  • Establece “Viewer protocol policy” en Redirect HTTP to HTTPS.
  • Establece “Allowed HTTP methods” en GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.

​
Default (*)

Edita el comportamiento de Default (*).
  1. Cambia Origin and origin groups del comportamiento predeterminado a la URL de staging (en nuestro caso, mintlify-landing-page.vercel.app).
  1. Selecciona Guardar cambios.

​
Verifica que hayas configurado los comportamientos correctamente

Si sigues los pasos anteriores, tus comportamientos deberían verse así:

​
Vista previa de la distribución

Para probar tu distribución, ve a la pestaña “General” y visita la URL de Distribution domain name.
Todas las páginas deberían enrutar a tu página de inicio principal. Cuando agregas la subruta que elegiste, por ejemplo /docs, la URL debería servir tu documentación de Mintlify.

​
Conectar con Route 53

A continuación, conecta la distribución de CloudFront a tu dominio principal.

​
Agregar tu dominio a la distribución

Primero, agrega tu dominio a la distribución de CloudFront. Sin un nombre de dominio alternativo, CloudFront rechaza las solicitudes que llegan a través de tu dominio.
  1. Abre la pestaña “General” de tu distribución y selecciona Edit en la sección “Settings”.
  2. Agrega tu dominio (por ejemplo, yoursite.com) como Alternate domain name (CNAME).
  3. En “Custom SSL certificate”, adjunta un certificado de AWS Certificate Manager (ACM) que cubra tu dominio.
CloudFront solo acepta certificados de ACM emitidos en la región US East (N. Virginia) us-east-1. Un certificado emitido en cualquier otra región no aparece en el menú “Custom SSL certificate”.

​
Crear el registro de Route 53

Para esta sección, también puedes consultar la guía oficial de AWS sobre Configurar Amazon Route 53 para enrutar el tráfico a una distribución de CloudFront, que cubre estos requisitos previos.
  1. Ve a Route53 en la consola de AWS.
  2. Ve a la “Hosted zone” de tu dominio principal.
  3. Selecciona Create record.
  1. Activa Alias y luego, en Route traffic to, selecciona la opción Alias to CloudFront distribution.
  1. Selecciona Create records.
Es posible que tengas que eliminar el registro A existente si ya hay uno.
Tu documentación ahora está disponible en la subruta elegida de tu dominio principal.
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.

Temas relacionados

Alojar la documentación en una subrutaDespliega en una subruta con VercelDespliega en una subruta con Cloudflare Workers