Partager via

Modèle De métadonnées et Markdown pour les documents .NET

Ce modèle dotnet/docs contient des exemples de syntaxe Markdown et des conseils sur la définition 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 le titre H1 ci-dessus sur 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 disposer d’un espace entre le signe deux-points (:) et la valeur d’un élément de métadonnées.
  • Les deux-points au sein d'une valeur (par exemple, un titre) perturbent le parseur de métadonnées. Dans ce cas, entourez le titre avec des guillemets doubles (par exemple, title: "Writing .NET Core console apps: An advanced step-by-step guide").
  • titre : apparaît dans les résultats du moteur de recherche. Le titre ne doit pas être identique au titre de votre titre H1, et il doit contenir 60 caractères ou moins.
  • description : résume le contenu de l’article. Il est généralement affiché dans la page des résultats de recherche, mais il n’est pas utilisé pour le classement de la recherche. Sa longueur doit être de 115 à 145 caractères, y compris les espaces.
  • auteur : le champ auteur doit contenir le nom d’utilisateur GitHub de l’auteur.
  • ms.date : date de la dernière mise à jour significative. Mettez-le à jour sur les articles existants si vous avez examiné et mis à jour l’intégralité de l’article. Les petits correctifs, tels que les fautes de frappe ou similaires, ne justifient pas une mise à jour.

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

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

Vous pouvez découvrir les bases de Markdown, le Markdown étendu de GitHub (GFM) et les extensions spécifiques à OPS dans l'article de référence 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 le neutraliser (par exemple, \* pour un *).
  • Utilisez le code d’entité HTML pour le caractère (par exemple, * pour un *).

Noms de fichiers

Les noms de fichiers utilisent les règles suivantes :

  • Contiennent uniquement des lettres minuscules, des chiffres et des traits d’union.
  • Aucun espace ou caractère de ponctuation. Utilisez les traits d’union pour séparer les mots et les nombres dans le nom de fichier.
  • Utilisez des verbes d’action spécifiques, tels que le développement, l’achat, la génération, la résolution des problèmes. Pas de mots se terminant par -ing.
  • Pas de petits mots - n’incluez pas un, et, dans, ou, etc.
  • Doit être dans Markdown et utiliser l’extension de fichier .md.
  • Conservez les noms de fichiers raisonnablement courts. Ils font partie de l’URL de vos articles.

En-têtes

Utilisez la mise en majuscules de style phrase. Mettez toujours en majuscule le premier mot d’un titre.

Styles de texte

Italics
Utiliser pour les fichiers, les dossiers, les chemins (les éléments longs doivent être placés sur une ligne séparée) et les nouveaux termes.

Bold
Utiliser pour les éléments d’interface utilisateur.

Code
Utilisez pour le code en ligne, les mots clés de langage, les noms de package NuGet, les commandes de ligne de commande, les noms de tables et colonnes de base de données, et les URL que vous ne souhaitez pas rendre cliquables.

Consultez l’article général sur les liens pour plus d’informations sur les ancres, les liens internes, les liens vers d’autres documents, le code inclut et les liens externes.

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

  • Dans la plupart des cas, nous utilisons les 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 lions à un fichier dans un dépôt dépendant, nous utilisons le caractère ~/ pour fournir le chemin d’accès. Étant donné que les fichiers du dépôt dépendant se trouvent dans un autre emplacement dans GitHub, les liens ne sont pas résolus correctement avec les liens relatifs, quelle que soit la façon dont ils ont été écrits.
  • La spécification du langage C# et la spécification du langage Visual Basic sont incluses dans la documentation .NET en incluant la source à partir des référentiels de langage. Les sources markdown sont gérées dans les référentiels csharplang et vblang .

Les liens vers la spécification doivent pointer vers les répertoires sources où ces spécifications sont incluses. 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 génération possède certaines extensions qui nous permettent de lier aux API .NET sans avoir à utiliser de liens externes. Vous utilisez 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 entièrement qualifié. Par défaut, le texte du lien affiche uniquement le nom du membre ou du type.

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

    Utilisez quand vous souhaitez personnaliser le texte du lien affiché.

Exemples :

  • <xref:System.String> s’affiche sous forme de chaîne
  • <xref:System.String?displayProperty=nameWithType> s’affiche en tant que System.String
  • [String class](xref:System.String) rend comme classe String

Pour plus d’informations sur l’utilisation de cette notation, consultez Utilisation de référence croisée.

Certains UID contiennent les caractères spéciaux « , # ou *, la valeur UID doit être encodée au format HTML en tant que %60, %23 et %2A respectivement. Vous verrez parfois des parenthèses encodées, mais ce n’est pas une exigence.

Exemples :

  • System.Threading.Tasks.Task`1 devient System.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

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

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

Pour créer un lien vers 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> lie au type System.Nullable<T>, tandis que <xref:System.Func%602> lie au délégué System.Func<T,TResult>.

Code

La meilleure façon d’inclure du code consiste à inclure des extraits de code à partir d’un exemple de travail. Créez votre exemple en suivant les instructions de l’article contributing to .NET. L’inclusion d’extraits de code à partir de programmes complets garantit que tout le code s’exécute via notre système d’intégration continue (CI). Toutefois, si vous devez afficher quelque chose qui provoque des erreurs de temps de compilation ou d’exécution, vous pouvez utiliser des blocs de code inline.

Pour plus d’informations sur la syntaxe Markdown pour afficher le code dans la documentation, consultez Guide pratique pour inclure du code dans la documentation.

Images

Image statique ou GIF animée

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

Image liée

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

Videos

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 pour Learn Microsoft

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

Listes vérifiées

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

Cela s’affiche comme suit :

  • Création d’une application .NET Core
  • Comment ajouter une référence au package Microsoft.XmlSerializer.Generator
  • Comment modifier votre MyApp.csproj pour ajouter des dépendances
  • Ajout d’une classe et d’un xmlSerializer
  • Comment générer et exécuter l’application

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

Buttons

Liens de bouton :

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

Cela s’affiche comme suit :

liens de bouton

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

Étapes pas à pas

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

Vous pouvez voir un exemple d’action pas à pas dans le Guide C#.

  • Last updated on