Partager via

Modèle de métadonnées et de Markdown pour la documentation .NET

  • Article

Ce modèle dotnet/docs contient des exemples de syntaxe Markdown, ainsi que des instructions sur la configuration des métadonnées.

Lors de la création d’un fichier Markdown, copiez le modèle inclus dans un nouveau fichier, renseignez les métadonnées comme indiqué ci-dessous et définissez l’en-tête H1 ci-dessus dans le titre de l’article.

Métadonnées

Le bloc de métadonnées requis se trouve dans l’exemple de bloc de métadonnées suivant :

---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents
  • Vous devez insérer un espace entre les deux-points (:) et la valeur d’un élément de métadonnées.
  • Les deux-points dans une valeur (par exemple un titre) rompent l’analyseur de métadonnées. Dans ce cas, placez le titre entre des guillemets doubles (par exemple title: "Writing .NET Core console apps: An advanced step-by-step guide").
  • title : apparaît dans les résultats des moteurs de recherche. Le titre ne doit pas être identique au titre de votre en-tête H1, et il doit contenir au plus 60 caractères.
  • description : fournit un récapitulatif du contenu de l’article. Elle est généralement affichée dans la page des résultats de la recherche, mais elle n’entre pas en compte pour le classement des recherches. Elle doit avoir une longueur comprise entre 115 et 145 caractères, espaces compris.
  • author : le champ author doit contenir le nom d’utilisateur GitHub de l’auteur.
  • ms.date : date de la dernière mise à jour importante. Mettez-la à jour dans les articles existants si vous avez révisé et mis à jour l’ensemble de l’article. Les petites corrections, telles que les fautes de frappe ou similaires, ne nécessitent pas de mise à jour.

D’autres métadonnées sont attachées à chaque article, mais nous appliquons en général la plupart des valeurs de métadonnées au niveau du dossier, spécifié dans docfx.json.

Markdown de base, GFM et caractères spéciaux

Pour découvrir les principes de base de Markdown, de GFM (GitHub Flavored Markdown) et des extensions propres à OPS, consultez l’article Informations de référence sur Markdown.

Markdown utilise des caractères spéciaux tels que *, ` et # pour la mise en forme. Si vous souhaitez inclure l’un de ces caractères dans votre contenu, vous devez effectuer l’une des deux opérations suivantes :

  • Placez une barre oblique inverse avant le caractère spécial pour l’« échapper » (par exemple \* pour *)
  • Utilisez le code d’entité HTML pour le caractère (par exemple * pour *).

Noms de fichiers

Les noms de fichiers suivent les règles ci-dessous :

  • Ils ne doivent contenir que des lettres, des chiffres et des traits d’union.
  • Ils ne doivent pas contenir d’espaces ni de caractères de ponctuation. Utilisez des traits d’union pour séparer les mots et les chiffres compris dans le nom de fichier.
  • Utilisez des verbes d’action spécifiques, tels que « développer », « acheter », « créer », « dépanner », etc. Ils ne doivent pas comprendre de mots se terminant par « -ing ».
  • Ils ne doivent pas comprendre de mots courts (« un », « et », « le », « en », « ou », etc.).
  • Ils doivent être au format Markdown et avoir l’extension de fichier .md.
  • Faites en sorte que les noms de fichiers soient le plus court possible. Ils font partie de l’URL de vos articles.

En-têtes

Utilisez les majuscules comme pour les phrases. Mettez toujours une majuscule au premier mot d’un titre.

Style de texte

Italique
À utiliser pour les fichiers, dossiers, chemins (les éléments longs doivent figurer sur leur propre ligne), nouveaux termes.

Gras
À utiliser pour les éléments d’interface utilisateur.

Code
À utiliser pour le code inline, les mots clés de langage, les noms des packages NuGet, les commandes de la ligne de commande, les noms des colonnes, les tables de base de données et les URL qui ne doivent pas être cliquables.

Pour plus d’informations sur les ancrages, les liens internes, les liens vers d’autres documents, les ajouts de code et les liens externes, consultez l’article général sur les Liens.

L’équipe de documentation .NET applique les conventions suivantes :

  • Dans la plupart des cas, nous utilisons des liens relatifs et déconseillons l’utilisation de ~/ dans les liens, car les liens relatifs sont résolus dans la source sur GitHub. Toutefois, chaque fois que nous établissons une liaison vers un fichier dans un dépôt dépendant, nous utilisons le caractère ~/ pour spécifier le chemin. Étant donné que les fichiers d’un dépôt dépendant sont à un emplacement différent dans GitHub, les liens relatifs ne seront pas résolus correctement, quelle que soit la manière dont ils sont écrits.
  • Les spécifications des langages C# et Visual Basic sont comprises dans la documentation .NET en incluant la source à partir des dépôts de langage. Les sources Markdown sont gérées dans les dépôts csharplang et vblang.

Les liens vers les spécifications doivent pointer vers les répertoires sources dans lesquels ces spécifications sont stockées. Pour C#, il s’agit de ~/_csharplang/spec, et pour VB, il s’agit de ~/_vblang/spec, comme dans l’exemple suivant :

[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

Le système de build comprend certaines extensions qui nous permettent d’établir des liaisons vers des API .NET sans avoir à recourir à des liens externes. Vous devez utiliser l’une des syntaxes suivantes :

  1. Lien automatique : <xref:UID> ou <xref:UID?displayProperty=nameWithType>

    Le paramètre de requête displayProperty produit un texte de lien complet. Par défaut, le texte du lien montre seulement le nom du membre ou du type.

  2. Lien Markdown : [link text](xref:UID)

    À utiliser quand vous voulez personnaliser le texte du lien affiché.

Exemples :

  • <xref:System.String> est rendu en tant que String
  • <xref:System.String?displayProperty=nameWithType> est rendu en tant que System.String
  • [String class](xref:System.String) est rendu en tant que classe String

Pour plus d’informations sur l’utilisation de cette notation, consultez Using cross reference.

Certains UID contiennent les caractères spéciaux `, # ou *. La valeur de l’UID doit être encodée en HTML en tant que %60, %23 et %2A, respectivement. Vous pouvez parfois trouver des parenthèses dans l’encodage, mais elles ne sont pas obligatoires.

Exemples :

  • System.Threading.Tasks.Task`1 devientSystem.Threading.Tasks.Task%601
  • System.Exception.#ctor devient System.Exception.%23ctor
  • System.Lazy`1.#ctor(System.Threading.LazyThreadSafetyMode) devient System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

Vous pouvez obtenir les UID des types, une liste des surcharges de membres ou un membre surchargé spécifique à partir dehttps://xref.learn.microsoft.com/autocomplete. La chaîne de requête ?text=*\<type-member-name>* identifie le type ou le membre dont vous souhaitez voir les UID. Par exemple, https://xref.learn.microsoft.com/autocomplete?text=string.format récupère les surcharges String.Format. L’outil recherche le paramètre de requête text fourni dans n’importe quelle partie de l’UID. Par exemple, vous pouvez rechercher le nom du membre (ToString), le nom du membre partiel (ToStri), le type et le le nom du membre (Double.ToString), et ainsi de suite.

Si vous ajoutez un * (ou un %2A) après l’UID, le lien représente alors la page de la surcharge et non une API spécifique. Par exemple, vous pouvez utiliser cela quand vous voulez créer un lien vers la page de la méthode List<T>.BinarySearch de façon générique, au lieu d’une surcharge spécifique, comme List<T>.BinarySearch(T, IComparer<T>). Vous pouvez aussi utiliser * pour établir une liaison vers une page de membre quand le membre n’est pas surchargé. Cela vous évite d’avoir à inclure la liste des paramètres dans l’UID.

Pour établir une liaison à une surcharge de méthode spécifique, vous devez inclure le nom de type qualifié complet de chacun des paramètres de la méthode. Par exemple, <xref:System.DateTime.ToString> établit une liaison à la méthode sans paramètre DateTime.ToString, tandis que <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> établit une liaison à la méthode DateTime.ToString(String,IFormatProvider).

Pour établir une liaison à un type générique, tel que System.Collections.Generic.List<T>, vous utilisez le caractère ` (%60) suivi du nombre de paramètres de type générique. Par exemple, <xref:System.Nullable%601> établit une liaison au type System.Nullable<T>, tandis que <xref:System.Func%602> établit une liaison au délégué System.Func<T,TResult>.

Code

Le meilleur moyen d’inclure du code consiste à inclure des extraits à partir d’un exemple opérationnel. Créez votre exemple en suivant les instructions fournies dans l’article Contribution à .NET. Le fait d’inclure des extraits tirés de programmes complets permet de s’assurer que tout le code transite par notre système d’intégration continue. Toutefois, si vous souhaitez afficher quelque chose qui provoque des erreurs de compilation ou d’exécution, vous pouvez utiliser des blocs de code inline.

Pour plus d’informations sur la syntaxe Markdown pour l’affichage du code dans des documents, consultez Inclure du code dans des documents.

Images

Image statique ou GIF animé

![this is the alt text](../images/Logo_DotNet.png)

Image liée

[![alt text for linked image](../images/Logo_DotNet.png)](https://dot.net)

Vidéos

Vous pouvez incorporer des vidéos YouTube dans un fichier Markdown. Pour obtenir l’URL correcte de la vidéo, cliquez avec le bouton droit sur la vidéo, sélectionnez Copier le code incorporé et copiez l’URL à partir de l’élément <iframe>.

> [!VIDEO <youtube_video_link>]

Par exemple :

> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

extensions learn.microsoft

learn.microsoft fournit quelques extensions supplémentaires pour GitHub Flavored Markdown.

Listes de cases à cocher

Un style personnalisé est disponible pour les listes. Vous pouvez afficher des listes avec des coches vertes.

> [!div class="checklist"]
> * How to create a .NET Core app
> * How to add a reference to the Microsoft.XmlSerializer.Generator package
> * How to edit your MyApp.csproj to add dependencies
> * How to add a class and an XmlSerializer
> * How to build and run the application

Ce code est restitué comme suit :

  • Guide pratique pour créer une application .NET Core
  • Guide pratique pour ajouter une référence au package Microsoft.XmlSerializer.Generator
  • Guide pratique pour modifier votre fichier MyApp.csproj afin d’ajouter des dépendances
  • Guide pratique pour ajouter une classe et un XmlSerializer
  • Guide pratique pour générer et exécuter l’application

Vous pouvez obtenir un exemple de listes vérifiées en action dans la documentation .NET Core.

Boutons

Liens de boutons :

> [!div class="button"]
> [button links](dotnet-contribute.md)

Ce code est restitué comme suit :

liens de boutons

Vous pouvez obtenir un exemple de boutons en action dans la documentation Visual Studio.

Pas à pas

>[!div class="step-by-step"]
> [Pre](../docs/csharp/expression-trees-interpreting.md)
> [Next](../docs/csharp/expression-trees-translating.md)

Vous pouvez obtenir un exemple de pas à pas en action dans le Guide C#.