Comment lier efficacement les pages de documentation

Créez des liens internes, des liens d’ancrage et des liens profonds dans votre documentation, et maintenez l’intégrité des liens avec des redirections et des vérifications de liens cassés.

Les liens connectent votre documentation en un système cohérent. Ils aident les utilisateurs à découvrir du contenu connexe, à naviguer efficacement et à suivre un chemin logique à travers des sujets complexes. Des liens médiocres—texte d’ancrage vague, références croisées manquantes, URLs cassées—rendent la documentation plus difficile à utiliser et nuisent au SEO.

Ce guide explique comment créer différents types de liens dans Mintlify et comment maintenir l’intégrité des liens à mesure que votre documentation évolue.

​

Liens internes

Liez vers d’autres pages de votre documentation en utilisant des chemins relatifs à la racine. Les chemins relatifs à la racine commencent à partir de la racine de votre répertoire de documentation et fonctionnent de manière cohérente, quel que soit l’emplacement de la page source dans votre structure de répertoires.

- [Quickstart guide](/quickstart)
- [API overview](/api-playground/overview)
- [Custom components](/customize/react-components)

Mintlify résout les chemins relatifs (./ et ../) en fonction de l’emplacement du fichier source dans le répertoire de votre projet. Cela fonctionne pour les liens, les images et les éléments JSX comme les balises <Card> et <a>.

- [Page voisine](./sibling-page)
- [Page de la section parente](../other-page)

Pour les fichiers index.mdx, les chemins relatifs sont résolus à partir du répertoire qui contient le fichier d’index. Par exemple, un lien ./setup dans guides/getting-started/index.mdx est résolu en /guides/getting-started/setup.

Les liens préservent les fragments et les chaînes de requête.

[Instructions de configuration](./setup#step-1)

Les chemins relatifs à la racine (commençant par /) fonctionnent mieux pour les liens internes car ils restent corrects si vous déplacez la page source vers un autre répertoire.

​

Liens d’ancrage

Les liens d’ancrage pointent vers des sections spécifiques au sein d’une page. Chaque titre génère automatiquement un ancrage basé sur son texte.

​

Lier vers des titres sur la même page

Référencez les titres de la page actuelle en utilisant le symbole dièse :

[Jump to best practices](#best-practices)

​

Lier vers des titres sur d’autres pages

Combinez le chemin de la page avec l’ancrage :

- [Customize your playground](/api-playground/overview#customize-your-playground)
- [Cards properties](/components/cards#properties)

​

Comment Mintlify génère les ancrages

Mintlify crée automatiquement des ancrages à partir du texte des titres en convertissant en minuscules, en remplaçant les espaces par des tirets et en supprimant les caractères spéciaux.

Texte du titre	Ancrage généré
## Getting Started	#getting-started
### API Authentication	#api-authentication
#### Step 1: Install	#step-1-install

Les titres avec la prop noAnchor ne génèrent pas de liens d’ancrage. Consultez Formater le texte pour plus de détails.

​

IDs d’ancrage personnalisés

Remplacez l’ancrage généré automatiquement pour n’importe quel titre en ajoutant {#custom-id} au texte du titre :

## Configuration options {#config}

Ce titre est accessible à #config au lieu de #configuration-options. Les IDs personnalisés maintiennent les liens d’ancrage stables lorsque vous mettez à jour le texte du titre—utile pour les titres vers lesquels vous liez fréquemment. Consultez Formater le texte pour plus de détails.

​

Liens profonds

Les liens profonds pointent vers des états ou des emplacements spécifiques au sein d’une page, pas seulement vers la page elle-même.

​

Liens profonds d’accordéon

Lorsqu’un utilisateur ouvre un accordéon, le hash de l’URL se met à jour pour refléter l’état ouvert. Visiter une URL avec ce hash ouvre automatiquement et fait défiler jusqu’à l’accordéon.

Par défaut, le hash est dérivé du title de l’accordéon. Utilisez la propriété id pour définir un hash personnalisé :

<Accordion title="Installation steps" id="install">
  ...
</Accordion>

Cet accordéon est accessible à #install au lieu du #installation-steps généré automatiquement. Consultez Accordéons pour en savoir plus.

​

Liens profonds de l’API playground

Pour ouvrir l’API playground dans un lien, ajoutez ?playground=open à n’importe quelle URL de page d’endpoint :

https://your-docs-url/endpoint-path?playground=open

L’URL se met à jour lorsque les utilisateurs ouvrent ou ferment le playground. Utilisez les liens profonds du playground dans les conversations de support ou les flux d’intégration pour envoyer les utilisateurs directement vers le playground interactif d’un endpoint. Consultez API playground pour des informations sur les liens d’ancrage de paramètres.

​

Liens externes

Lorsque vous liez vers des ressources externes, rédigez un texte d’ancrage qui rend la destination claire :

See the [OpenAPI specification](https://swagger.io/specification/) in the Swagger documentation for details.

​

Bonnes pratiques

​

Rédigez un texte d’ancrage descriptif

Le texte d’ancrage doit indiquer aux utilisateurs où ils vont avant qu’ils ne cliquent. Les phrases vagues comme “cliquez ici” ou “en savoir plus” sont également des signaux SEO plus faibles que le texte descriptif.

Good

See [Hidden pages](/organize/hidden-pages) for more information.
[Configure custom domains](/customize/custom-domain)

​

Liez les prérequis explicitement

Lorsqu’une page suppose des étapes préalables, liez-les en haut plutôt que de supposer que les utilisateurs les trouveront :

## Prerequisites

Before deploying your documentation, ensure you have:

- Completed the [quickstart guide](/quickstart)
- Configured your [custom domain](/customize/custom-domain)
- Set up [authentication](/deploy/authentication-setup) if needed

​

Construisez des clusters de sujets

Liez le contenu connexe ensemble pour aider les utilisateurs—et les moteurs de recherche—à comprendre comment votre documentation est organisée :

## Related topics

- [API authentication](/api-playground/overview#authentication)
- [Adding SDK examples](/api-playground/adding-sdk-examples)
- [Managing page visibility](/api-playground/managing-page-visibility)

​

Vérifiez les liens cassés

Exécutez le CLI de Mintlify avant de publier pour détecter les liens internes et externes cassés :

mint broken-links

​

Mettez à jour les liens lors d’une réorganisation

Lors du déplacement ou du renommage de pages :

1. Mettez à jour le chemin de la page dans votre configuration de navigation.
2. Configurez des redirections de l’ancien chemin vers le nouveau chemin.
3. Recherchez dans votre documentation les références à l’ancien chemin.
4. Mettez à jour tous les liens internes pour utiliser le nouveau chemin.
5. Exécutez mint broken-links pour vérifier.

​

Utilisez des redirections pour le contenu déplacé

Lors du déplacement permanent de contenu, ajoutez des redirections pour éviter les liens cassés pour les utilisateurs qui ont mis en favoris ou partagé les anciennes URLs.

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

Consultez Redirections pour plus d’informations.

​

Questions fréquemment posées

Dois-je utiliser des chemins relatifs à la racine ou des URLs absolues pour les liens internes ?

Les chemins relatifs à la racine (commençant par /) sont le choix le plus courant pour les liens internes dans Mintlify. Ils fonctionnent de manière cohérente quel que soit l’emplacement de la page source dans votre répertoire, et ils ne se cassent pas si votre domaine de documentation change. Les URLs absolues pour les liens internes créent une fragilité inutile.

Vous pouvez utiliser des chemins relatifs (./ et ../), mais comme ils sont résolus en fonction de l’emplacement du fichier source, ils peuvent se casser plus fréquemment.

Comment maintenir les liens d'ancrage stables lorsque je mets à jour les titres ?

Utilisez des IDs d’ancrage personnalisés pour les titres vers lesquels vous liez fréquemment. Ajouter {#custom-id} à un titre découple l’ancrage du texte du titre, afin que vous puissiez mettre à jour le texte du titre sans casser les liens qui pointent vers lui. C’est particulièrement utile pour les titres dans les sections de référence à fort trafic où le texte peut nécessiter des ajustements au fil du temps.

Que se passe-t-il avec les liens mis en favoris lorsque je réorganise ma documentation ?

Sans redirections, les liens mis en favoris et partagés deviennent des erreurs 404. Configurez des redirections dans votre docs.json chaque fois que vous déplacez ou renommez une page. Les redirections sont peu coûteuses à ajouter et évitent une mauvaise expérience utilisateur pour quiconque a lié vers votre documentation depuis une source externe—articles de blog, réponses Stack Overflow, wikis internes.

Combien de liens internes une page devrait-elle contenir ?

Liez lorsqu’un concept connexe est véritablement utile à l’utilisateur à ce moment précis—pas pour atteindre un quota. Trop peu de liens laissent les utilisateurs sans contexte ni prochaines étapes. Trop de liens transforment la page en un exercice de navigation qui éloigne les utilisateurs de ce qu’ils essaient de faire. En règle générale, liez la première mention d’un concept ou d’un outil, et ne répétez pas le même lien plusieurs fois sur une seule page.

​

Ressources connexes

• Formater le texte : Options de formatage Markdown incluant les IDs de titres et le comportement des ancrages.
• Navigation : Configurez la structure de votre documentation.
• Redirections : Configurez des redirections pour le contenu déplacé.