Domaine personnalisé

Hébergez votre documentation sur un domaine personnalisé avec une configuration DNS, des certificats TLS automatiques et des options de routage par sous-domaine ou sous-chemin.

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.

Vous souhaitez configurer un sous-chemin comme example.com/docs ? Consultez /docs subpath.

​

Ajoutez votre domaine personnalisé

1. Accédez à la page Configuration du domaine personnalisé dans votre Dashboard.
2. Saisissez votre nom de domaine. Par exemple, docs.example.com ou www.example.com.
3. Cliquez sur Ajouter le domaine.

​

Configurez votre DNS

1. Sur le site web de votre fournisseur de domaine, accédez aux paramètres DNS de votre domaine.
2. Créez un nouvel enregistrement DNS avec les valeurs suivantes :

CNAME | docs | cname.mintlify.builders

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.

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.

​

Enregistrements TXT de vérification

Après avoir ajouté un domaine personnalisé, le dashboard affiche deux enregistrements TXT que vous devez ajouter chez votre fournisseur DNS :

TXT | _acme-challenge.<votre-domaine> | <valeur affichée dans votre dashboard>
TXT | _cf-custom-hostname.<votre-domaine> | <valeur affichée dans votre dashboard>

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.

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.

​

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. Vous pouvez vérifier que votre DNS est correctement configuré avec DNSChecker.

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.

​

Provisionnement automatique de TLS

Une fois vos enregistrements TXT ajoutés et vos enregistrements DNS résolus correctement, un certificat SSL/TLS gratuit est automatiquement généré pour votre site avec 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 domain utilise des enregistrements CAA (Certification Authority Authorization), vous devez autoriser Let’s Encrypt à émettre des certificats pour votre domain. Ajoutez l’enregistrement CAA suivant à vos paramètres DNS :

0 problème "letsencrypt.org"

​

Chemins réservés

Le chemin /.well-known/acme-challenge est réservé à la validation de certificats et ne peut pas être redirigé ni réécrit. Si vous avez configuré des redirections ou des réécritures pour ce chemin, l’émission du certificat échoue.

​

Paramètres spécifiques au fournisseur

Mode de chiffrement Cloudflare

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 de la mise à disposition du certificat.

​

Relancer la validation

Après l’ajout d’un enregistrement TXT de vérification, la validation du domaine peut entrer dans une période d’attente et les nouvelles tentatives peuvent prendre plusieurs heures. Si vous avez déjà ajouté les enregistrements DNS corrects et que votre domaine reste en attente de validation, relancez la validation manuellement depuis votre Dashboard pour contourner l’attente.

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.

N’utilisez cette option qu’après avoir vérifié que vos enregistrements DNS sont corrects. Relancer la validation avec des enregistrements incorrects n’accélère pas le processus.

​

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 domain personnalisé réel. Par exemple, si votre domain personnalisé est docs.mintlify.com, vous utiliseriez :

"seo": {
    "metatags": {
        "canonical": "https://docs.mintlify.com"
    }
}