Skip to main content
Configurez votre fichier vercel.json pour acheminer les requêtes de votre domaine principal vers votre documentation sur un sous-chemin.

Le fichier vercel.json

Le fichier vercel.json définit la façon dont votre projet est construit et déployé. Il se trouve à la racine de votre projet et contrôle divers aspects de votre déploiement, notamment le routage, les redirections, les en-têtes et les paramètres de build. Nous utilisons la configuration rewrites dans votre fichier vercel.json pour faire transiter les requêtes de votre domaine principal vers votre documentation via un proxy. Les réécritures (rewrites) font correspondre les requêtes entrantes à différentes destinations sans modifier l’URL dans le navigateur. Quand quelqu’un visite yoursite.com/docs, Vercel récupère en interne le contenu depuis your-subdomain.mintlify.site/docs, mais l’utilisateur voit toujours yoursite.com/docs dans son navigateur. Cela diffère des redirections, qui envoient les utilisateurs vers une URL complètement différente.

Configuration

Héberger sur le sous-chemin /docs

  1. Accédez à Configuration du domaine personnalisé dans votre Dashboard.
  2. Activez le bouton Host at.
  3. Saisissez votre domaine.
  4. Saisissez docs comme chemin de base.
  5. Cliquez sur Add domain.
  6. Ajoutez les réécritures suivantes à votre fichier vercel.json. Remplacez [subdomain] par votre sous-domaine, que vous trouverez à la fin de l’URL de votre Dashboard. Par exemple, app.mintlify.com/your-organization/your-subdomain possède un identifiant de domaine your-subdomain.
La configuration rewrites fait correspondre le sous-chemin /docs sur votre domaine au sous-chemin /docs sur votre documentation.
  • source : Le modèle de chemin sur votre domaine qui déclenche la réécriture.
  • destination : L’endroit où la requête doit être transmise en proxy.
  • :match* : Un joker qui capture tous les segments de chemin après votre sous-chemin.
Les réécritures /_mintlify et /mintlify-assets sont requises pour le playground d’API et les ressources statiques. Pour plus d’informations, consultez Configuring projects with vercel.json: Rewrites dans la documentation Vercel.

Héberger sur un sous-chemin personnalisé

Pour utiliser un sous-chemin personnalisé (tout chemin autre que /docs) :
  1. Accédez à la page Configuration du domaine personnalisé dans votre Dashboard.
  2. Activez le bouton Host at et saisissez votre chemin de base. Par exemple, /docs ou /help.
  3. Saisissez votre domaine.
  4. Saisissez votre chemin de base.
  5. Cliquez sur Add domain.
Utilisez ensuite le générateur ci-dessous pour créer votre configuration de réécritures et ajoutez-les à votre fichier vercel.json. Mintlify reconstruit votre documentation pour la servir sur votre chemin de base, vos fichiers de documentation n’ont donc pas besoin de se trouver dans un répertoire correspondant à votre sous-chemin.

Proxys externes devant Vercel

Si vous utilisez un proxy externe comme Cloudflare ou AWS CloudFront devant votre déploiement Vercel, configurez-le correctement. Cela permet d’éviter les conflits avec la vérification de domaine de Vercel et l’approvisionnement des certificats SSL. Une mauvaise configuration du proxy peut empêcher Vercel d’approvisionner des certificats SSL Let’s Encrypt et entraîner des échecs de vérification de domaine. Consultez les fournisseurs pris en charge dans la documentation Vercel.

Liste d’autorisation de chemins obligatoire

Votre proxy externe doit autoriser le trafic vers ces chemins spécifiques sans le bloquer, le rediriger ni le mettre en cache de manière agressive :
  • /.well-known/acme-challenge/* : requis pour la vérification de certificat Let’s Encrypt.
  • /.well-known/vercel/* : requis pour la vérification de domaine Vercel.
  • /mintlify-assets/_next/static/* : requis pour les ressources statiques.
Votre proxy doit transmettre ces chemins directement à votre déploiement Vercel sans modification.

Exigences relatives au transfert des en-têtes

Assurez-vous que votre proxy transfère correctement l’en-tête Host. Sans un transfert correct des en-têtes, les requêtes de vérification échouent.

Tester la configuration de votre proxy

Pour vérifier que votre proxy est correctement configuré :
  1. Vérifiez que https://[yourdomain].com/.well-known/vercel/ renvoie une réponse.
  2. Assurez-vous que les certificats SSL sont correctement provisionnés dans votre dashboard Vercel.
  3. Vérifiez que la vérification du domaine se termine avec succès.