Skip to main content
Configura tu archivo vercel.json para reenviar mediante un proxy las solicitudes desde tu dominio principal a tu documentación en una subruta.

El archivo vercel.json

El archivo vercel.json configura cómo se compila e implementa tu proyecto. Se encuentra en el directorio raíz de tu proyecto y controla varios aspectos de la implementación, como el enrutamiento, las redirecciones, los encabezados y la configuración de compilación. Mintlify utiliza la configuración de rewrites en tu archivo vercel.json para enrutar las solicitudes desde tu dominio principal hacia tu documentación mediante un proxy. Las reglas de reescritura (rewrites) asignan las solicitudes entrantes a distintos destinos sin cambiar la URL en el navegador. Cuando alguien visita yoursite.com/docs, Vercel obtiene internamente el contenido desde your-subdomain.mintlify.site/docs, pero el usuario sigue viendo yoursite.com/docs en su navegador. Esto es diferente de las redirecciones, que envían a los usuarios a otra URL por completo.

Configuración

Alojar en la subruta /docs

  1. Ve a la configuración de dominio personalizado en tu dashboard.
  2. Habilita el interruptor Host at.
  3. Ingresa tu dominio.
  4. Ingresa docs como tu ruta base.
  5. Haz clic en Add domain.
  6. Agrega las siguientes reglas de reescritura a tu archivo vercel.json. Sustituye [subdomain] por tu subdominio, que se encuentra al final de la URL de tu dashboard. Por ejemplo, app.mintlify.com/your-organization/your-subdomain tiene un identificador de dominio de your-subdomain.
La configuración de rewrites asigna la subruta /docs en tu dominio a la subruta /docs en tu documentación.
  • source: El patrón de ruta en tu dominio que activa la reescritura.
  • destination: Adonde se debe enviar la solicitud mediante proxy.
  • :match*: Un comodín que captura cualquier segmento de ruta después de tu subruta.
Las reglas de reescritura de /_mintlify y /mintlify-assets son obligatorias para el API playground y los recursos estáticos. Para obtener más información, consulta Configuring projects with vercel.json: Rewrites en la documentación de Vercel.

Hospedar en una subruta personalizada

Para usar una subruta personalizada (cualquier ruta distinta de /docs):
  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.
Luego utiliza el generador a continuación para crear tu configuración de rewrites y añade las reglas de rewrites a tu archivo vercel.json. Mintlify reconstruye tu documentación para servirla en tu ruta base, por lo que tus archivos de documentación no necesitan estar en un directorio que coincida con tu subruta.

Proxies externos delante de Vercel

Si tienes un proxy externo como Cloudflare o AWS CloudFront delante de tu implementación en Vercel, configúralo correctamente. Esto evita conflictos con la verificación de dominio de Vercel y el aprovisionamiento de certificados SSL. Una configuración incorrecta del proxy puede impedir que Vercel aprovisione certificados SSL de Let’s Encrypt y provocar errores en la verificación del dominio. Consulta los proveedores compatibles en la documentación de Vercel.

Lista obligatoria de rutas permitidas

Tu proxy externo debe permitir el tráfico a estas rutas específicas sin bloquear, redirigir ni aplicar un almacenamiento en caché agresivo:
  • /.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.
  • /mintlify-assets/_next/static/*: Obligatoria para los recursos estáticos.
Tu proxy debe pasar estas rutas directamente a tu implementación de Vercel sin modificaciones.

Requisitos de reenvío de encabezados

Asegúrate de que tu proxy reenvíe correctamente el encabezado Host. Sin un reenvío adecuado de encabezados, las solicitudes de verificación fallan.

Probar la configuración de tu proxy

Para verificar que tu proxy esté configurado correctamente:
  1. Verifica que https://[yourdomain].com/.well-known/vercel/ devuelva una respuesta.
  2. Asegúrate de que los certificados SSL se estén aprovisionando correctamente en tu dashboard de Vercel.
  3. Comprueba que la verificación del dominio se complete correctamente.