Passer au contenu principal
Hébergez votre documentation sur votre propre domaine, comme docs.example.com, ou sur un sous-chemin de votre domaine, comme example.com/docs. Pour héberger votre documentation sur un domaine personnalisé :
  1. Ajoutez votre domaine dans votre Dashboard.
  2. Configurez les paramètres DNS auprès de votre fournisseur de domaine.
  3. Laissez le temps nécessaire au DNS pour se propager et aux certificats TLS d’être automatiquement provisionnés.

​
Choisir où héberger votre documentation

Vous pouvez héberger votre documentation à la racine d’un domaine, sur un sous-domaine ou sur un sous-chemin. Domaine ou sous-domaine : hébergez votre documentation sur un domaine comme example.com ou un sous-domaine comme docs.example.com. Mintlify sert l’ensemble du trafic du domaine ou du sous-domaine. L’hébergement sur un domaine sans sous-domaine nécessite un fournisseur DNS qui prend en charge le CNAME flattening ou les enregistrements ALIAS. Consultez Apex domains. Sous-chemin : hébergez votre documentation sur un chemin de votre domaine, comme example.com/docs. Activez le bouton Host at lorsque vous ajoutez votre domaine et saisissez votre chemin de base. La façon dont le trafic atteint Mintlify dépend de votre DNS :
  • Si le DNS de votre domaine pointe vers Mintlify, Mintlify sert votre documentation à votre sous-chemin. Ne faites pointer votre domaine vers Mintlify que s’il n’héberge aucun autre contenu et que Mintlify peut recevoir tous les chemins du domaine.
  • Si un autre site fonctionne sur votre domaine, votre application ou votre CDN continue de recevoir le trafic du domaine et transmet uniquement votre sous-chemin à Mintlify via un proxy.
L’hébergement sur un sous-chemin n’est pas pris en charge pour la documentation avec authentification activée.

​
Ajoutez votre domaine personnalisé

  1. Accédez à la page Configuration du domaine personnalisé dans votre Dashboard.
  2. Pour héberger sur un sous-chemin, activez le bouton Host at et saisissez votre chemin de base, par exemple /docs.
  3. Saisissez votre nom de domaine. Par exemple, docs.example.com ou example.com.
  4. Cliquez sur Add domain.
Si le trafic de votre domaine est acheminé vers Mintlify, le Dashboard affiche les enregistrements DNS à ajouter chez votre fournisseur de domaine. Si vous ne transmettez que votre sous-chemin à Mintlify via un proxy, le Dashboard affiche à la place des guides de configuration de proxy inverse. Suivez le guide correspondant à votre fournisseur et consultez Héberger la documentation sur un sous-chemin pour plus d’informations.

​
Exigences relatives au chemin de base

Votre chemin de base peut être n’importe quel chemin qui remplit les conditions suivantes :
  • Commence par / et ne contient ni espaces, ni chaînes de requête, ni fragments.
  • Comporte au maximum 128 caractères.
  • N’est pas un chemin réservé par Mintlify : /_next, /_mintlify, /_sites, /_live-preview, /api, /login, /logout, /mcp, /feedback, /openapi-specs.download, /llms.txt, /llms-full.txt, /sitemap.xml, /robots.txt, /skill.md et /.well-known.

​
Modifier votre chemin de base

Lorsque vous modifiez votre chemin de base ou votre sous-chemin, Mintlify reconstruit et redéploie votre site. Votre site reste en ligne au chemin actuel jusqu’à la fin du déploiement, puis le trafic bascule vers le nouveau chemin. Si le déploiement échoue, votre site continue d’être servi depuis le chemin actuel et vous pouvez relancer la modification depuis votre Dashboard.

​
Configurez votre DNS

Chaque fournisseur de domaine a des méthodes différentes pour ajouter des enregistrements DNS. Consultez la documentation de votre fournisseur de domaine pour des instructions spécifiques.
  1. Sur le site web de votre fournisseur de domaine, accédez aux paramètres DNS de votre domaine.
  2. Créez les enregistrements DNS affichés dans votre Dashboard.
Le Dashboard affiche des enregistrements de vérification TXT et un enregistrement CNAME : 
TXT | _acme-challenge.<votre-domaine> | <valeur affichée dans votre dashboard>
TXT | _cf-custom-hostname.<votre-domaine> | <valeur affichée dans votre dashboard>
CNAME | <votre-domaine> | cname.mintlify.builders
L’enregistrement _acme-challenge autorise Let’s Encrypt à émettre un certificat TLS pour votre domaine, et l’enregistrement _cf-custom-hostname vérifie que vous contrôlez le domaine.
Ajoutez d’abord vos enregistrements TXT. N’ajoutez pas et ne modifiez pas votre CNAME tant que les deux enregistrements TXT de vérification n’apparaissent pas comme vérifiés dans votre Dashboard. Chacun s’affiche avec une coche verte lorsque le DNS est correct. Le Dashboard vérifie les enregistrements TXT avant que le provisionnement du certificat puisse aboutir. Modifier le CNAME trop tôt casse fréquemment le HTTPS jusqu’à la fin du provisionnement.Si vous migrez un domaine existant et souhaitez aucun temps d’arrêt, publiez d’abord les enregistrements TXT de vérification et attendez qu’ils apparaissent comme vérifiés et que TLS soit pré-provisionné avant de pointer le CNAME vers Mintlify.Ce flux de pré-validation ne fonctionne pas pour les domaines derrière un proxy Cloudflare. Consultez Domaines derrière un proxy Cloudflare.
Le Dashboard interroge le DNS en arrière-plan et marque chaque enregistrement d’une coche verte une fois qu’il vérifie la valeur attendue. Après avoir enregistré les enregistrements chez votre fournisseur DNS, prévoyez un court délai de propagation avant que les statuts ne soient mis à jour.

​
Domaines apex

Si vous hébergez votre documentation à un domaine apex comme example.com sans sous-domaine, votre fournisseur DNS doit prendre en charge le CNAME flattening ou un type d’enregistrement virtuel comme ALIAS ou ANAME. Le DNS standard ne permet pas d’avoir un enregistrement CNAME à l’apex d’un domaine, donc les fournisseurs qui ne prennent pas en charge ces options ne peuvent pas créer l’enregistrement affiché dans votre Dashboard. Parmi les fournisseurs qui prennent en charge les enregistrements CNAME apex figurent Cloudflare (CNAME flattening), Amazon Route 53 (enregistrements alias), DNSimple (enregistrements ALIAS) et Porkbun (enregistrements ALIAS). Si votre fournisseur ne prend en charge aucune de ces options, hébergez plutôt votre documentation sur un sous-domaine comme docs.example.com.

​
Propagation du DNS

Les modifications DNS se propagent généralement en 1 à 24 heures dans le monde entier, mais cela peut prendre jusqu’à 48 heures dans certains cas. Utilisez un outil comme DNSChecker pour vérifier que votre configuration DNS est correcte. Une fois vos enregistrements DNS actifs, votre documentation est d’abord accessible en HTTP. Le HTTPS sera disponible après le provisionnement de votre certificat TLS par Mintlify.

​
Provisionnement automatique de TLS

Après avoir ajouté vos enregistrements TXT et une fois vos enregistrements DNS résolus correctement, Mintlify génère un certificat SSL/TLS gratuit pour votre site à l’aide de Let’s Encrypt. Cette étape s’achève généralement dans les heures qui suivent la propagation DNS, bien que cela puisse prendre jusqu’à 24 heures dans de rares cas. Les certificats sont automatiquement renouvelés avant leur expiration.

​
Enregistrements CAA

Si votre domaine utilise des enregistrements CAA (Certification Authority Authorization), vous devez autoriser Let’s Encrypt à émettre des certificats pour votre domaine. Ajoutez l’enregistrement CAA suivant à vos paramètres DNS : 
0 issue "letsencrypt.org"

​
Chemins réservés

Mintlify réserve le chemin /.well-known/acme-challenge pour la validation des certificats. Vous ne pouvez pas rediriger ni réécrire ce chemin. Si vous avez configuré des redirections ou des réécritures pour ce chemin, l’émission du certificat échoue.

​
Domaines derrière un proxy Cloudflare

Si votre domaine est déjà derrière un proxy Cloudflare (le statut du proxy affiche un nuage orange), les enregistrements TXT de vérification ne peuvent pas apparaître comme vérifiés avant que vous ne mettiez à jour votre CNAME. Cela se produit même lorsque les enregistrements se résolvent correctement avec des outils comme dig ou DNSChecker. Le proxy Cloudflare empêche la vérification d’aboutir tant que le trafic pour le nom d’hôte n’est pas acheminé vers Mintlify. Pour les domaines derrière un proxy Cloudflare, procédez comme suit :
  1. Ajoutez les enregistrements TXT de vérification chez votre fournisseur DNS.
  2. Mettez à jour votre enregistrement CNAME pour pointer vers cname.mintlify.builders sans attendre que les enregistrements TXT apparaissent comme vérifiés.
  3. Attendez que la vérification et le provisionnement TLS se terminent. Votre site peut brièvement servir un certificat invalide pendant le provisionnement.
Si vous avez besoin d’une migration sans temps d’arrêt, réglez plutôt le statut du proxy de l’enregistrement CNAME sur DNS only (nuage gris). Cela permet au flux de pré-validation standard d’aboutir avant de basculer le trafic.

​
Paramètres spécifiques au fournisseur

Si Cloudflare est votre fournisseur DNS, vous devez activer le mode “Full (strict)” pour le paramètre de chiffrement SSL/TLS. Désactivez également “Always Use HTTPS” dans vos paramètres Edge Certificates. La redirection HTTPS de Cloudflare empêche Let’s Encrypt de valider votre domaine lors du provisionnement du certificat.

​
Relancer la validation

Les enregistrements TXT sont généralement validés en cinq minutes. Si votre domaine reste en attente de validation après avoir ajouté les enregistrements TXT de vérification, relancez la validation manuellement depuis votre Dashboard.
  1. Accédez à la page Configuration du domaine personnalisé dans votre Dashboard.
  2. Repérez votre domaine personnalisé en attente.
  3. Cliquez sur Retry validation.
Ne relancez la validation qu’après avoir vérifié que vos enregistrements DNS sont corrects. Des relances répétées avec des enregistrements incorrects n’accélèrent pas la validation.

​
Supprimer un domaine personnalisé

Pour supprimer un domaine personnalisé, cliquez sur l’icône de suppression à côté de votre domaine sur la page Configuration du domaine personnalisé et confirmez la suppression. Les liens existants vers ce domaine peuvent cesser de fonctionner, et le réajout du domaine peut nécessiter de reconfigurer vos enregistrements DNS.

​
Définir une URL canonique

Après avoir configuré votre DNS, définissez une URL canonique pour indiquer aux moteurs de recherche d’indexer votre domaine préféré. Une URL canonique précise aux moteurs de recherche quelle version de votre documentation est la principale. Cela améliore le SEO lorsque votre documentation est accessible via plusieurs URL et évite les problèmes de contenu dupliqué. Ajoutez la balise meta canonical à votre docs.json : 
"seo": {
    "metatags": {
        "canonical": "https://www.your-custom-domain-here.com"
    }
}
Remplacez https://www.your-custom-domain-here.com par votre domaine personnalisé réel. Par exemple, si votre domaine personnalisé est docs.mintlify.com, vous utiliseriez : 
"seo": {
    "metatags": {
        "canonical": "https://docs.mintlify.com"
    }
}