Pour héberger votre documentation sous un sous-chemin personnalisé tel que yoursite.com/docs avec Cloudflare, vous devrez créer et configurer un Cloudflare Worker.
Avant de commencer, vous devez disposer d’un compte Cloudflare et d’un nom de domaine (géré sur Cloudflare ou ailleurs).
yoursite.com/docs, créez un répertoire docs/ contenant tous vos fichiers de documentation.
Créez un Cloudflare Worker en suivant le guide de démarrage de Cloudflare Workers, si ce n’est pas déjà fait.
Si votre fournisseur DNS est Cloudflare, n’activez pas le proxy pour l’enregistrement CNAME.
Proxies avec des déploiements Vercel
Liste d’autorisation de chemins requise
/.well-known/acme-challenge/* - Requis pour la vérification du certificat Let’s Encrypt/.well-known/vercel/* - Requis pour la vérification de domaine Vercel
Bien que Cloudflare gère automatiquement de nombreuses règles de vérification, la création de règles personnalisées supplémentaires peut, par inadvertance, bloquer ce trafic essentiel.
Assurez-vous que l’en-tête HOST est correctement transmis dans la configuration de votre Worker. Une mauvaise transmission des en-têtes provoquera l’échec des requêtes de vérification.
Dans votre tableau de bord Cloudflare, sélectionnez Edit Code et ajoutez le script suivant au code de votre Worker. Consultez la documentation Cloudflare pour en savoir plus sur la modification d’un Worker.
Remplacez [SUBDOMAIN] par votre sous-domaine unique, [YOUR_DOMAIN] par l’URL de base de votre site web, et /docs par le sous-chemin souhaité, le cas échéant.
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});
async function handleRequest(request) {
try {
const urlObject = new URL(request.url);
// Si la requête vise un chemin de vérification Vercel, laissez-la passer
if (urlObject.pathname.startsWith('/.well-known/')) {
return await fetch(request);
}
// Si la requête cible le sous-répertoire des docs
if (/^\/docs/.test(urlObject.pathname)) {
// Alors mettre en proxy vers Mintlify
const DOCS_URL = "[SUBDOMAIN].mintlify.dev";
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");
// Si vous déployez sur Vercel, préserver l’IP du client
proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
return await fetch(proxyRequest);
}
} catch (error) {
// Si aucune action n’est trouvée, exécuter la requête normale
return await fetch(request);
}
}
Après avoir configuré votre DNS, les sous-domaines personnalisés sont généralement disponibles en quelques minutes. La propagation du DNS peut parfois prendre 1 à 4 heures, et dans de rares cas jusqu’à 48 heures. Si votre sous-domaine n’est pas immédiatement disponible, veuillez patienter avant d’entreprendre tout dépannage.
- Testez en utilisant l’URL d’aperçu du Worker :
your-worker.your-subdomain.workers.dev/docs
- Vérifiez que le Worker achemine correctement vers votre documentation Mintlify et votre site web.
Ajouter un domaine personnalisé
- Dans votre tableau de bord Cloudflare, accédez à votre Worker.
- Allez dans Settings > Domains & Routes > Add > Custom Domain.
- Ajoutez votre domaine.
Nous vous recommandons d’ajouter votre domaine à la fois avec et sans le préfixe www..
Résoudre les conflits DNS
- Supprimez l’enregistrement DNS existant de votre domaine. Consultez la section Supprimer des enregistrements DNS dans la documentation Cloudflare pour en savoir plus.
- Retournez à votre Worker et ajoutez votre domaine personnalisé.
Routage personnalisé Webflow
/docs sur le même domaine, vous devrez configurer un routage personnalisé via Cloudflare Workers afin de faire proxy de tout le trafic non lié à la doc vers votre site principal.
Assurez-vous que votre site principal pointe vers une page d’accueil (landing page) avant de déployer ce Worker, sinon les visiteurs de votre site principal verront des erreurs.
- Dans Webflow, configurez une page d’accueil (landing page) pour votre site principal, par exemple
landing.yoursite.com. Ce sera la page que les visiteurs verront lorsqu’ils se rendront sur votre site.
- Déployez votre site principal sur cette page d’accueil. Cela garantit que votre site principal reste accessible pendant la configuration du Worker.
- Pour éviter les conflits, remplacez les URL absolues de votre site principal par des URL relatives.
- Dans Cloudflare, sélectionnez Edit Code et ajoutez le script suivant dans le code de votre Worker.
Remplacez [SUBDOMAIN] par votre sous-domaine unique, [YOUR_DOMAIN] par l’URL de base de votre site, [LANDING_DOMAIN] par l’URL de votre page d’accueil, et /docs par le sous-chemin souhaité, le cas échéant.
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});
async function handleRequest(request) {
try {
const urlObject = new URL(request.url);
// Si la requête vise un chemin de vérification Vercel, laissez-la passer
if (urlObject.pathname.startsWith('/.well-known/')) {
return await fetch(request);
}
// Si la requête vise le sous-répertoire docs
if (/^\/docs/.test(urlObject.pathname)) {
// Faire transiter via Mintlify (proxy)
const DOCS_URL = "[SUBDOMAIN].mintlify.dev";
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");
// Si vous déployez sur Vercel, conservez l’IP du client
proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
return await fetch(proxyRequest);
}
// Acheminer tout le reste vers le site principal
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) {
// Si aucune action n’est trouvée, traiter la requête normalement
return await fetch(request);
}
}
- Sélectionnez Deploy et attendez que les modifications se propagent.
Après avoir configuré votre DNS, les sous-domaines personnalisés sont généralement disponibles en quelques minutes. La propagation du DNS peut parfois prendre 1 à 4 heures, et dans de rares cas jusqu’à 48 heures. Si votre sous-domaine n’est pas immédiatement disponible, veuillez patienter avant d’entreprendre tout dépannage.
