Utiliser des liens dans la documentation

Cet article décrit comment utiliser des liens hypertexte à partir de pages hébergées sur Microsoft Learn. Vous pouvez facilement ajouter des liens dans la syntaxe Markdown en tenant compte de quelques conventions. Les liens pointent vers du contenu situé dans la même page, dans d’autres pages voisines ou vers des sites et des URL externes.

Le back-end Microsoft Learn utilise OPS (Open Publishing Services) qui prend en charge Markdown conforme avec CommonMark analysé via le moteur Markdig. Ce type Markdown est essentiellement compatible avec GitHub Flavored Markdown (GFM), car la plupart des documents sont stockés dans GitHub et peuvent être modifiés à cet endroit. Des fonctionnalités sont ajoutées via des extensions Markdown.

Texte du lien

Les mots que vous incluez dans le texte doivent être conviviaux. En d’autres termes, il doit s’agir de mots simples ou du titre de la page vers laquelle vous établissez le lien.

Correct :

• For more information, see the [contributor guide index](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

• For more details, see the [SET TRANSACTION ISOLATION LEVEL](/sql/t-sql/statements/set-transaction-isolation-level-transact-sql) reference.

Incorrect :

• For more details, see [https://msdn.microsoft.com/library/ms173763.aspx](https://msdn.microsoft.com/library/ms173763.aspx).

• For more information, click [here](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

Liens d'un article à un autre

Il existe deux types de liens hypertextes pris en charge par le système de publication : les URL et les liens de fichiers.

Un lien URL peut être un chemin d’URL relatif à la racine de https://learn.microsoft.com ou une URL absolue qui inclut la syntaxe complète de l’URL (par exemple, https://github.com/MicrosoftDocs/PowerShell-Docs).

• Utilisez un lien URL pour établir un lien vers du contenu situé en dehors du docset actif ou entre des articles de référence et conceptuels générés automatiquement dans le docset.
• Le moyen le plus simple de créer un lien relatif consiste à copier l’URL à partir de votre navigateur, puis à supprimer https://learn.microsoft.com/en-us de la valeur que vous collez dans le code Markdown.
• N’incluez pas de paramètres régionaux dans les URL pour les propriétés Microsoft (par exemple, supprimez /en-us de l’URL).

Un lien vers un fichier permet de lier un article à un autre dans le docset.

• Tous les chemins à des fichiers utilisent des barres obliques (/), et non des barres obliques inverses.

• Un article a un lien vers un autre article du même répertoire :

  [link text](article-name.md)

• Un article a un lien vers un article du répertoire parent du répertoire actif :

  [link text](../article-name.md)

• Un article a un lien vers un article d’un sous-répertoire du répertoire actif :

  [link text](directory/article-name.md)

• Un article a un lien vers un article d’un sous-répertoire du répertoire parent du répertoire actif :

  [link text](../directory/article-name.md)

• Certains articles se composent d’un fichier .yml et d’un fichier .md, où le fichier .yml contient des métadonnées et le fichier .md renferme le contenu. Dans ce cas, redirigez vers le fichier .yml :

  [link text](../directory/article-name.yml) (et non [link text](../directory/article-name-content.md))

Structure des liens sur Microsoft Learn

Le contenu publié sur Microsoft Learn repose sur la structure d’URL suivante :

https://learn.microsoft.com/<locale>/<product-service>/[<feature-service>]/[<subfolder>]/<topic>[?view=<view-name>]

Exemples :

https://learn.microsoft.com/azure/load-balancer/load-balancer-overview

https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1

• <locale> - Identifie la langue de l’article (par exemple : en-us ou fr-fr)
• <product-service> - Nom du produit ou du service (par exemple : powershell, dotnet ou azure)
• [<feature-service>] (facultatif) - Nom de la fonctionnalité ou du sous-service du produit (par exemple : csharp ou load-balancer)
• [<subfolder>] (facultatif) - Nom d’un sous-dossier dans une fonctionnalité
• <topic> - Nom du fichier de l’article pour la rubrique (par exemple : load-balancer-overview ou overview)
• [?view=\<view-name>] (facultatif) - Nom de la vue utilisée par le sélecteur de version pour du contenu disponible dans plusieurs versions (par exemple : azps-3.5.0)

Liens de signet

Pour établir un lien vers un titre marqué d’un signet dans le fichier actif, utilisez un symbole de hachage suivi des mots du titre en minuscules. Supprimez les signes de ponctuation dans le titre et remplacez les espaces par des tirets :

[Managed Disks](#managed-disks)

Pour établir un lien vers un titre marqué d’un signet dans un autre article, utilisez le lien relatif à un fichier ou relatif à un site plus un symbole dièse, suivi des mots du titre. Supprimez les signes de ponctuation dans le titre et remplacez les espaces par des tirets :

[Managed Disks](../../linux/overview.md#managed-disks)

Vous pouvez également copier le lien vers le signet à partir de l’URL. Pour trouver l’URL, pointez votre souris sur la ligne du titre sur Microsoft Learn. Vous devriez voir une icône de lien :

Cliquez sur l’icône de lien, puis copiez le texte de l’ancre du signet à partir de l’URL (c’est-à-dire la partie située après le hachage).

Liens d’ancrage explicites

L’ajout de liens vers des ancres explicites utilisant la balise HTML <a> n’est ni obligatoire ni recommandé, sauf dans les pages hub et d’arrivée. Utilisez plutôt les signets générés automatiquement, comme décrit dans Liens de signet. Pour les pages hub et d’arrivée, déclarez les ancres comme ceci :

## <a id="anchortext" />Header text

or

## <a name="anchortext" />Header text

Ajoutez ce qui suit pour établir un lien vers l’ancre :

To go to a section on the same page:
[text](#anchortext)

To go to a section on another page.
[text](filename.md#anchortext)

Liens XRef (référence croisée)

Les liens XRef sont la méthode recommandée pour établir des liens vers des API, car ils facilitent la personnalisation du texte du lien. En outre, ils sont validés au moment de la génération et si l’URL de la référence d’API doit changer, le lien fonctionne toujours. Pour créer un lien vers des pages de références d’API générées automatiquement dans le docset actif ou dans d’autres docsets, utilisez des liens XRef avec l’ID unique (UID) du type ou membre.

Vérifiez que l’API vers laquelle doit pointer votre lien est publiée Microsoft Learn. Pour cela, tapez tout ou partie de son nom complet dans la zone de recherche du navigateur d’API .NET ou de Windows UWP. Si aucun résultat n’est retourné, le type n’est pas encore sur Microsoft Learn.

Vous pouvez utiliser une des syntaxes suivantes :

• Liens automatiques :

  <xref:UID>
  <xref:UID?displayProperty=nameWithType>
  

  Par défaut, le texte du lien affiche seulement le nom du membre ou du type. Le paramètre de requête displayProperty=nameWithType facultatif produit un texte de lien complet, à savoir namespace.type pour les types et type.member pour les membres de type, notamment les membres de type énumération.

• Liens de style Markdown :

  [link text](xref:UID)
  

  Utilisez des liens de style Markdown pour XRef quand vous souhaitez personnaliser le texte du lien affiché.

Exemples :

• <xref:System.String> apparaît sous la forme String.

• <xref:System.String?displayProperty=nameWithType> apparaît sous la forme System.String.

• [String class](xref:System.String) apparaît sous la forme String class.

Le paramètre de requête displayProperty=fullName fonctionne de la même façon que displayProperty=nameWithType pour les classes. Autrement dit, le texte du lien devient namespace.classname. Toutefois, pour les membres, le texte du lien apparaît sous la forme namespace.classname.membername, ce qui peut être indésirable.

Déterminer l’UID

L’UID est généralement le nom complet de la classe ou du membre. Pour déterminer l’UID, cliquez avec le bouton droit sur la page Microsoft Learn pour un type ou un membre, sélectionnez Afficher la source, puis copiez la valeur content pour ms.assetid.

Encodage en pourcent des URL

Les caractères spéciaux de l’UID doivent être encodés selon la méthode de l'encodage-pourcent comme ceci :

Exemple d’encodage :

• System.Exception.#ctor est encodé sous la forme System.Exception.%23ctor.

Types génériques

Les types génériques sont des types tels que System.Collections.Generic.List<T>. Si vous accédez à ce type dans le navigateur d’API .NET et que vous examinez son URL, vous pouvez voir que <T> est écrit -1 dans l’URL, ce qui représente en fait `1 :

https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1

Méthodes

Pour établir un lien vers une méthode, vous pouvez soit créer un lien vers la page de la méthode générale en ajoutant un astérisque (*) après le nom de la méthode, soit créer un lien vers une surcharge spécifique. Par exemple, utilisez la page générale quand vous souhaitez établir un lien vers la méthode <xref:System.Object.Equals*?displayProperty=nameWithType> sans types de paramètres spécifiques. Par exemple :

<xref:System.Object.Equals*?displayProperty=nameWithType> crée un lien vers Object.Equals

Pour établir un lien vers une surcharge spécifique, ajoutez des parenthèses après le nom de la méthode et placez dans celles-ci le nom de type complet de chaque paramètre. N’insérez aucun espace entre les noms de types ; sinon, le lien ne fonctionnera pas. Par exemple :

<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> crée un lien vers Object.Equals(Object, Object)

Liens des includes

Les fichiers include étant situés dans un autre répertoire, vous devez utiliser des chemins d'accès relatifs plus longs. Pour faire un lien vers un article à partir d'un fichier include, utilisez ce format :

[link text](../articles/folder/article-name.md)

Liens dans les sélecteurs

Un sélecteur est un composant de navigation qui apparaît dans un article de documentation sous forme de liste déroulante. Quand un lecteur sélectionne une valeur dans la liste déroulante, le navigateur ouvre l’article sélectionné. En général, la liste du sélecteur contient des liens vers des articles qui ont un rapport étroit avec celui-ci, par exemple traitant du même sujet dans différents langages de programmation, ou vers une série d’articles connexe.

Si vous avez des sélecteurs intégrés dans un include, utilisez la structure de liens suivante :

> [AZURE.SELECTOR-LIST (Dropdown1 | Dropdown2 )]
- [(Text1 | Example1 )](../articles/folder/article-name1.md)
- [(Text1 | Example2 )](../articles/folder/article-name2.md)
- [(Text2 | Example3 )](../articles/folder/article-name3.md)
- [(Text2 | Example4 )](../articles/folder/article-name4.md)

Liens de type référence

Vous pouvez utiliser des liens de type référence pour rendre votre contenu source plus facile à lire. Les liens de type référence remplacent la syntaxe de lien inline par une syntaxe simplifiée vous permettant de déplacer les URL longues à la fin de l’article. Voici l'exemple de Daring Fireball :

Texte intégré :

I get 10 times more traffic from [Google][1] than from [Yahoo][2] or [MSN][3].

Liens de référence à la fin de l'article :

<!--Reference links in article-->
[1]: http://google.com/
[2]: http://search.yahoo.com/
[3]: http://search.msn.com/

Veillez à inclure l’espace après le signe deux-points, avant le lien. Lorsque vous liez d'autres articles techniques, si vous oubliez d'inclure l'espace, le lien sera rompu dans l’article publié.

Liens vers des pages qui ne font pas partie de l’ensemble de documentation technique

Pour établir un lien vers une page sur une autre propriété de Microsoft (par exemple la page de tarifs, la page du contrat SLA ou toute autre page qui n’est pas un article de documentation), utilisez une URL absolue, mais omettez les paramètres régionaux. Le but ici est que les liens fonctionnent dans GitHub et sur le site rendu :

[link text](https://azure.microsoft.com/pricing/details/virtual-machines/)

Liens vers des sites tiers

Une expérience utilisateur idéale minimise l'envoi d'utilisateurs vers d'autres sites. Basez donc les liens vers des sites tiers, dont nous avons parfois besoin, sur ces informations :

• Responsabilité : Établissez un lien vers du contenu tiers quand il s’agit des informations que le tiers est tenu de partager. Par exemple, il ne revient pas à Microsoft d’expliquer aux utilisateurs comment utiliser les outils pour développeurs d’Android. Cette tâche incombe à Google. Si besoin, nous pouvons expliquer comment utiliser les outils Android avec Azure, mais l'explication de l'utilisation des outils eux-mêmes est le travail de Google.
• Validation des PM : Demandez à Microsoft de valider le contenu tiers. En établissant un lien, nous donnons des indications de notre confiance et de nos obligations si les utilisateurs suivent les instructions.
• Révisions d’actualisation : Vérifiez que les informations tierces sont toujours actuelles, correctes et pertinentes, et que le lien n’a pas changé.
• Hors site : Informez les utilisateurs qu’ils vont vers un autre site. Si le contexte ne l’indique pas explicitement, ajoutez une phrase pour cela, par exemple « Les conditions requises comprennent les outils de développement d’Android, que vous pouvez télécharger sur le site d’Android Studio ».
• Étapes suivantes : Vous pouvez ajouter un lien vers, par exemple, un blog MVP dans une section « Étapes suivantes ». Encore une fois, vérifiez que les utilisateurs comprennent qu’ils vont quitter le site.
• Juridique : Nous sommes légalement couverts sous Liens vers des sites tiers dans les Conditions d’utilisation en pied de page de chaque page microsoft.com.