vercel.json para reenviar mediante un proxy las solicitudes desde tu dominio principal a tu documentación en una subruta.
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.
- Ve a la configuración de dominio personalizado en tu dashboard.
-
Ingresa tu dominio seguido de
/docs. Por ejemplo,example.com/docs. - Haz clic en Add domain.
-
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-subdomaintiene un identificador de dominio deyour-subdomain.
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.
/_mintlify es obligatoria. Sirve el CSS, JavaScript, fuentes y solicitudes de API de tu sitio desde la raíz de tu dominio. Sin ella, las páginas se cargan sin estilos. La regla de reescritura de /mintlify-assets sirve favicons y recursos estáticos en algunos sitios. Mantén ambas reglas de reescritura en la raíz de tu dominio, sin tu subruta.
Para obtener más información, consulta Configuring projects with vercel.json: Rewrites en la documentación de Vercel.
Para usar una subruta personalizada (cualquier ruta distinta de /docs):
- Ve a la página de configuración de dominio personalizado en tu dashboard.
- Ingresa tu dominio seguido de tu ruta base. Por ejemplo,
example.com/docsoexample.com/help. - Haz clic en Add domain.
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.
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.
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/*: Obligatoria para CSS, JavaScript, fuentes y solicitudes de API./mintlify-assets/*: Obligatoria para favicons y recursos estáticos en algunos sitios.
Host. Sin un reenvío adecuado de encabezados, las solicitudes de verificación fallan.
Para verificar que tu proxy esté configurado correctamente:
- Verifica que
https://[yourdomain].com/.well-known/vercel/devuelva una respuesta. - Asegúrate de que los certificados SSL se estén aprovisionando correctamente en tu dashboard de Vercel.
- Comprueba que la verificación del dominio se complete correctamente.