yoursite.com/docs via Cloudflare, vous devez créer et configurer un Cloudflare Worker.
Avant de commencer, vous avez besoin d’un compte Cloudflare et d’un nom de domaine (géré avec ou sans Cloudflare).
Définir votre chemin de base
- Accédez à la page Configuration du domaine personnalisé dans votre Dashboard.
- Activez le bouton Host at et saisissez votre chemin de base. Par exemple,
/docsou/help. - Saisissez votre domaine.
- Saisissez votre chemin de base.
- Cliquez sur Add domain.
Configurer un Worker
Proxies avec des déploiements Vercel
Liste blanche de chemins requise
/.well-known/acme-challenge/*- Requis pour la vérification de certificat Let’s Encrypt/.well-known/vercel/*- Requis pour la vérification de domain Vercel
Exigences de transfert des en-têtes
Host sur votre cible <subdomain>.mintlify.site, comme illustré dans le script d’exemple, plutôt que de transmettre l’en-tête Host de la requête d’origine. Des en-têtes Host incorrects entraînent l’échec des requêtes de vérification.
Configurer le routage
Après avoir déployé vos modifications, votre documentation est généralement accessible à votre sous-chemin en quelques minutes. Si votre configuration inclut des changements DNS, la propagation peut prendre de 1 à 4 heures, et dans de rares cas jusqu’à 48 heures. Si votre documentation n’est pas immédiatement accessible, patientez avant d’essayer de résoudre le problème.
Testez votre Worker
- Testez en utilisant l’URL d’aperçu du Worker :
your-worker.your-subdomain.workers.dev/docs - Vérifiez que le Worker redirige vers votre documentation Mintlify et votre site web.
Ajouter un domaine personnalisé
- Dans votre Dashboard Cloudflare, accédez à votre Worker.
- Allez dans Settings > Domains & Routes > Add > Custom Domain.
- Ajoutez votre domaine.
Résoudre les conflits DNS
- Supprimez l’enregistrement DNS existant pour votre domaine. Consultez la section Delete DNS records de la documentation Cloudflare pour plus d’informations.
- Retournez à votre Worker et ajoutez votre domaine personnalisé.
Routage personnalisé avec Webflow
/docs sur le même domaine, vous devrez configurer un routage personnalisé via Cloudflare Workers pour faire transiter (proxy) tout le trafic non lié à la documentation vers votre site principal.
- Dans Webflow, configurez une page d’atterrissage pour votre site principal, par exemple
landing.yoursite.com. C’est la page que les visiteurs voient lorsqu’ils visitent votre site. - Déployez votre site principal sur la page d’atterrissage. Cela garantit que votre site principal reste accessible pendant que vous configurez le Worker.
- Pour éviter les conflits, mettez à jour toutes les URL absolues de votre site principal pour qu’elles soient relatives.
- Dans Cloudflare, sélectionnez Edit Code et ajoutez le script suivant dans le code de votre Worker.
- Sélectionnez Deploy et attendez que les modifications se propagent.
Après avoir déployé vos modifications, votre documentation est généralement accessible à votre sous-chemin en quelques minutes. Si votre configuration inclut des changements DNS, la propagation peut prendre de 1 à 4 heures, et dans de rares cas jusqu’à 48 heures. Si votre documentation n’est pas immédiatement accessible, patientez avant d’essayer de résoudre le problème.
Dépanner le blocage par le pare-feu
Symptômes
- La page de documentation se charge d’abord, puis plante avec une erreur 500 au bout de 30 à 60 secondes.
- Navigation côté client lente ou défaillante entre les pages.
- Erreurs 403 dans la console du navigateur pour les requêtes vers les chemins
/mintlify-assets/*. - Messages de sécurité Cloudflare évoquant des « données malformées » ou des « modèles d’URL suspects ».
Cause racine
- La présence de plusieurs symboles
%dans les paramètres d’URL encodés. - De longues chaînes de requête avec des caractères spéciaux.
- Des requêtes automatisées provenant d’onglets inactifs.
Solution
Créer l’exception de pare-feu
- Connectez-vous à votre Cloudflare dashboard.
- Sélectionnez votre domaine.
- Accédez à Security > WAF.
- Cliquez sur Create rule.
- Configurez la règle avec ces paramètres :
- Field:
Hostname - Operator:
equals - Value:
docs.yourdomain.com(remplacez par le domaine réel de votre documentation)
- Field:
URI Path - Operator:
starts with - Value:
/mintlify-assets/
- Action:
Skip - Select:
All remaining custom rules,Managed rules, andSuper Bot Fight Mode
- Activez Log pour suivre les requêtes correspondantes.
- Cliquez sur Deploy.
Vérifier la règle
- Ouvrez votre site de documentation dans un navigateur.
- Laissez la page inactive pendant 2 à 3 minutes.
- Naviguez entre les pages.
- Vérifiez la console du navigateur pour voir s’il y a des erreurs 403.
- Assurez-vous que le nom d’hôte correspond exactement à votre domaine de documentation.
- Confirmez que le chemin URI utilise « starts with » (et non « contains »).
- N’incluez pas de caractères génériques (
*) dans la valeur du chemin. - Vérifiez que vous avez activé et déployé la règle.
Erreurs courantes
- Utiliser l’opérateur
containsavec/mintlify-assets/*. Le*est interprété comme un caractère littéral, pas comme un caractère générique. - Utiliser
equalspour le chemin URI. Cela ne fait correspondre que le chemin exact/mintlify-assets/et non les sous-chemins. - Oublier d’exclure le Bot Fight Mode. Incluez-le explicitement dans l’action d’exclusion.
- Définir un nom d’hôte incorrect. Il doit correspondre à votre domaine de documentation réel.
Résolution de problèmes supplémentaire
- Consultez le journal Security > Events de Cloudflare pour identifier les requêtes bloquées.
- Vérifiez que votre Cloudflare Worker (si vous utilisez un sous-chemin personnalisé) définit l’en-tête
Hostsur votre cible<subdomain>.mintlify.siteau lieu de transmettre l’en-têteHostde la requête d’origine. - Réglez temporairement le niveau de sécurité sur « Essentially Off » pour confirmer que Cloudflare est bien en cause.
- Vérifiez d’éventuelles Page Rules personnalisées susceptibles d’outrepasser l’exception du pare-feu.