Pour héberger votre documentation sur un sous-chemin personnalisé tel que yoursite.com/docs avec Cloudflare, vous devrez créer et configurer un Cloudflare Worker.
Avant de commencer, vous avez besoin d’un compte Cloudflare et d’un nom de domaine (qui peut être géré sur ou hors de Cloudflare).

​
Structure du dépôt

Organisez vos fichiers de documentation dans votre dépôt pour qu’ils correspondent à la structure de sous-chemin choisie. Par exemple, si vous souhaitez que votre documentation soit accessible à l’adresse yoursite.com/docs, créez un répertoire docs/ contenant tous vos fichiers de documentation.

​
Configurer un Cloudflare Worker

Créez un Cloudflare Worker en suivant le guide de démarrage des 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.

​
Proxys avec des déploiements Vercel

Si vous utilisez Cloudflare comme proxy avec des déploiements Vercel, vous devez veiller à une configuration adéquate pour éviter les conflits avec la vérification de domaine de Vercel et l’émission des certificats SSL. Une mauvaise configuration du proxy peut empêcher Vercel d’émettre des certificats SSL Let’s Encrypt et entraîner des échecs de vérification de domaine.

​
Liste d’autorisation de chemins requise

Votre Cloudflare Worker doit autoriser le trafic vers ces chemins spécifiques sans le bloquer ni le rediriger :
  • /.well-known/acme-challenge/* - Nécessaire pour la vérification des certificats Let’s Encrypt
  • /.well-known/vercel/* - Nécessaire 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 critique.

​
Exigences de transmission des en-têtes

Assurez-vous que l’en-tête HOST est correctement transmis dans la configuration de votre Worker. Si les en-têtes ne sont pas correctement transmis, les requêtes de vérification échoueront.

​
Configurer le routage

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 plus d’informations 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é s’il est différent.
addEventListener("fetch", (event) => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
  try {
    const urlObject = new URL(request.url);
    
    // Si la requête cible 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 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, conservez l’IP 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écutez la requête normale
    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 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 votre Worker

Après le déploiement de votre code, testez votre Worker pour vous assurer qu’il achemine vers votre documentation Mintlify.
  1. Testez à l’aide de l’URL de prévisualisation du Worker : your-worker.your-subdomain.workers.dev/docs
  2. Vérifiez que le Worker achemine bien vers votre documentation Mintlify et votre site web.

​
Ajouter un domaine personnalisé

  1. Dans votre tableau de bord Cloudflare, accédez à votre Worker.
  2. Allez dans Settings > Domains & Routes > Add > Custom Domain.
  3. Ajoutez votre domaine.
Nous vous recommandons d’ajouter votre domaine à la fois avec et sans le préfixe www..
Consultez la section Add a custom domain dans la documentation Cloudflare pour en savoir plus.

​
Résoudre les conflits DNS

Si votre domaine pointe déjà vers un autre service, vous devez supprimer l’enregistrement DNS existant. Votre Worker Cloudflare doit être configuré pour gérer l’intégralité du trafic de votre domaine.
  1. Supprimez l’enregistrement DNS existant de votre domaine. Consultez la page Supprimer des enregistrements DNS dans la documentation Cloudflare pour en savoir plus.
  2. Retournez sur votre Worker et ajoutez votre domaine personnalisé.

​
Routage personnalisé avec Webflow

Si vous utilisez Webflow pour héberger votre site principal et souhaitez servir la documentation Mintlify à /docs sur le même domaine, vous devrez configurer un routage personnalisé via Cloudflare Workers afin de proxyer tout le trafic non lié à la documentation 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.
  1. Dans Webflow, configurez une page d’accueil pour votre site principal, par exemple landing.yoursite.com. Ce sera la page que les visiteurs verront lorsqu’ils accéderont à votre site.
  2. Déployez votre site principal sur cette page d’accueil. Cela garantit que votre site principal reste accessible pendant que vous configurez le Worker.
  3. Pour éviter les conflits, remplacez dans votre site principal les URL absolues par des URL relatives.
  4. 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 web, [LANDING_DOMAIN] par l’URL de votre page d’accueil, et /docs par le sous-chemin souhaité si différent. 
  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 subdirectory
    if (/^\/docs/.test(urlObject.pathname)) {
      // Proxy to 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");
      // 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);
  }
  }
  1. 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 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.