Redirections

Configurez des redirections d’URL dans docs.json pour les pages déplacées, renommées ou supprimées afin de préserver le SEO et d’éviter les liens brisés.

Lorsque vous modifiez le chemin d’un fichier dans votre dossier docs, l’URL de cette page change également. Cela peut se produire lors de la restructuration de votre documentation ou de la modification du titre de la barre latérale.

​

Redirections

Les sources de redirection ne peuvent pas inclure des ancres d’URL telles que path#anchor ni des paramètres de requête tels que path?query=value. Les destinations peuvent inclure des ancres (par exemple /destination/path#section).

Ajoutez le champ redirects au niveau racine de votre fichier docs.json pour configurer des redirections.

docs.json

{
  "name": "My docs",
  "redirects": [
    {
      "source": "/source/path",
      "destination": "/destination/path"
    }
  ]
}

Cela redirige /source/path vers /destination/path.

Par défaut, les redirections sont permanentes (308). Pour utiliser une redirection temporaire (307), définissez permanent sur false.

"redirects": [
  {
    "source": "/source/path",
    "destination": "/destination/path",
    "permanent": false
  }
]

Les codes 307 et 308 conservent tous deux la méthode HTTP de la requête d’origine (contrairement à 301 et 302), ce qui les rend adaptés à la redirection des requêtes POST.

Utilisez une redirection permanente (308) lorsqu’une page a été déplacée définitivement — pour des slugs renommés, une navigation restructurée ou des pages supprimées qui pointent vers un remplacement. Les moteurs de recherche transfèrent le classement SEO vers la destination et les navigateurs mettent la redirection en cache.

Utilisez une redirection temporaire (307) pour un reroutage à court terme lorsque l’URL source doit revenir, comme les pages de maintenance, les tests A/B ou les liens de campagne que vous prévoyez de réutiliser. Les moteurs de recherche conservent l’URL source dans leur index et ne transfèrent pas le classement.

​

Limites de redirections

Il n’y a pas de plafond strict sur le nombre de redirections que vous pouvez définir dans docs.json. De très grands tableaux de redirections (des milliers d’entrées) peuvent ralentir les déploiements et rendre le fichier plus difficile à examiner ; consolidez donc avec des redirections avec joker lorsque c’est possible.

​

Redirections avec joker

Pour faire correspondre un chemin avec joker, utilisez * après un paramètre. Dans cet exemple, /beta/:slug* correspond à /beta/introduction et le redirige vers /v2/introduction.

"redirects": [
  {
    "source": "/beta/:slug*",
    "destination": "/v2/:slug*"
  }
]

​

Redirections avec jokers partiels

Utilisez des jokers partiels pour faire correspondre les segments d’URL qui commencent par un préfixe donné.

"redirects": [
  {
    "source": "/articles/concepts-*",
    "destination": "/collections/overview"
  }
]

Cela correspond à toutes les URL dont le chemin est /articles/concepts-, comme /articles/concepts-getting-started et /articles/concepts-overview, et les redirige toutes vers /collections/overview.

Vous pouvez également réutiliser la valeur générique capturée dans la destination.

"redirects": [
  {
    "source": "/old/article-*",
    "destination": "/new/article-*"
  }
]

Cela redirige /old/article-123 vers /new/article-123, tout en conservant la valeur capturée après le préfixe.

​

Éviter les redirections infinies

Pour éviter les boucles infinies, ne créez pas de redirections circulaires dans lesquelles les chemins se renvoient les uns aux autres.

"redirects": [
  {
    "source": "/docs/:slug*",
    "destination": "/help/:slug*"
  },
  {
    "source": "/help/:slug*",
    "destination": "/docs/:slug*"
  }
]

​

Quand les redirections prennent effet

Les redirections définies dans docs.json s’appliquent au moment de la requête sur la couche d’hébergement de Mintlify : elles sont donc actives dès que vos modifications sont déployées. Les déploiements de preview appliquent également les redirections, ce qui vous permet de vérifier leur comportement avant de fusionner dans votre branche de production.

Pour tester les redirections en local, exécutez mint dev et visitez le chemin source dans votre navigateur. Le serveur de développement local applique les redirections définies dans votre docs.json.

​

Vérifier les liens cassés

Détectez les liens cassés avec la CLI.

mint broken-links