Redirections

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.

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

{
  "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.

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.

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*"
  }
]

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.

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*"
  }
]

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 se déploient. 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.

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

mint broken-links