Para alojar tu documentación en una subruta como 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).
- 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,
/docs o /help.
- Ingresa tu dominio.
- Ingresa tu ruta base.
- Haz clic en Add domain.
El dashboard muestra un script de Cloudflare Worker con tu subdominio, dominio y ruta base ya completados. Usa este script en el paso Configurar el enrutamiento en lugar de reemplazar manualmente los valores de marcador de posición en el script de ejemplo.
Crea un Cloudflare Worker siguiendo la guía de inicio de Cloudflare Workers, si aún no lo has hecho.
Si tu proveedor de DNS es Cloudflare, desactiva el proxy para el registro CNAME para evitar posibles problemas de configuración.
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
Aunque Cloudflare gestiona automáticamente muchas reglas de verificación, crear reglas personalizadas adicionales puede bloquear inadvertidamente este tráfico crítico.
Asegúrate de que tu Worker establezca el encabezado 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.
En tu dashboard de Cloudflare, haz clic en Edit Code y añade el script de tu página de configuración de dominio personalizado, que tiene tus valores ya completados, o copia el siguiente script de ejemplo. Consulta la documentación de Cloudflare para obtener más información sobre cómo editar un Worker.
Si usas el script de ejemplo, reemplaza [SUBDOMAIN] por tu subdominio único, [YOUR_DOMAIN] por la URL base de tu sitio web y /docs por la subruta que desees si es diferente.
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});
async function handleRequest(request) {
try {
const urlObject = new URL(request.url);
// If the request is to a Vercel verification path, allow it to pass through
if (urlObject.pathname.startsWith('/.well-known/')) {
return await fetch(request);
}
// If the request is to the docs subpath
if (/^\/docs/.test(urlObject.pathname)) {
// Then Proxy to Mintlify
const DOCS_URL = "[SUBDOMAIN].mintlify.site";
const CUSTOM_URL = "[YOUR_DOMAIN]";
let url = new URL(request.url);
url.hostname = DOCS_URL;
let proxyRequest = new Request(url, request);
proxyRequest.headers.set("Host", DOCS_URL);
proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
proxyRequest.headers.set("X-Forwarded-Proto", "https");
// If deploying to Vercel, preserve client IP
proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
return await fetch(proxyRequest);
}
} catch (error) {
// If no action found, play the regular request
return await fetch(request);
}
}
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 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.
Agrega tu dominio tanto con www. como sin www. al inicio.
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.
Configura tu sitio principal en una landing page antes de desplegar este Worker, o los visitantes de tu sitio principal podrían ver errores.
- 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.
Reemplaza [SUBDOMAIN] por tu subdominio único, [YOUR_DOMAIN] por la URL base de tu sitio web, [LANDING_DOMAIN] por la URL de tu landing page y /docs por la subruta que desees si es diferente.
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});
async function handleRequest(request) {
try {
const urlObject = new URL(request.url);
// If the request is to a Vercel verification path, allow it to pass through
if (urlObject.pathname.startsWith('/.well-known/')) {
return await fetch(request);
}
// If the request is to the docs subpath
if (/^\/docs/.test(urlObject.pathname)) {
// Proxy to Mintlify
const DOCS_URL = "[SUBDOMAIN].mintlify.site";
const CUSTOM_URL = "[YOUR_DOMAIN]";
let url = new URL(request.url);
url.hostname = DOCS_URL;
let proxyRequest = new Request(url, request);
proxyRequest.headers.set("Host", DOCS_URL);
proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
proxyRequest.headers.set("X-Forwarded-Proto", "https");
// If deploying to Vercel, preserve client IP
proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
return await fetch(proxyRequest);
}
// Route everything else to main site
const MAIN_SITE_URL = "[LANDING_DOMAIN]";
if (MAIN_SITE_URL && MAIN_SITE_URL !== "[LANDING_DOMAIN]") {
let mainSiteUrl = new URL(request.url);
mainSiteUrl.hostname = MAIN_SITE_URL;
return await fetch(mainSiteUrl, {
method: request.method,
headers: request.headers,
body: request.body
});
}
} catch (error) {
// If no action found, serve the regular request
return await fetch(request);
}
}
- 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.
