Bonnes pratiques relatives au Markdown

Cet article fournit des conseils spécifiques sur l’utilisation de Markdown dans notre documentation. Ce n’est pas un tutoriel pour Markdown. Si vous avez besoin d’un didacticiel pour Markdown, consultez cette aide-mémoire Markdown.

Le pipeline de build qui génère notre documentation utilise Markdig pour traiter les documents Markdown. Markdig analyse les documents en fonction des règles de la dernière spécification CommonMark . OPS suit la spécification CommonMark et ajoute certaines extensions pour les fonctionnalités spécifiques à la plateforme, telles que les tables et les alertes.

La spécification CommonMark est plus stricte au sujet de la construction de certains éléments Markdown. Attention particulière aux détails fournis dans ce document.

Nous utilisons l’extension markdownlint dans VS Code pour appliquer nos règles de style et de mise en forme. Cette extension est installée dans le cadre de Learn Authoring Pack.

Lignes, espaces et onglets vides

Les lignes vides signalent également la fin d’un bloc dans Markdown.

• Placez un seul vide entre les blocs Markdown de différents types ; par exemple, entre un paragraphe et une liste ou un en-tête.
• N’utilisez pas plusieurs lignes vides. Plusieurs lignes vides s’affichent sous la forme d’une seule ligne vide en HTML, par conséquent, les lignes vides supplémentaires sont inutiles.
• N’utilisez pas plusieurs lignes vides consécutives dans un bloc de code, les lignes vides consécutives interrompent le bloc de code.

L’espacement est important dans Markdown.

• Supprimez des espaces supplémentaires à la fin des lignes. Les espaces de fin peuvent modifier le rendu Markdown.
• Utilisez toujours des espaces plutôt que des onglets (onglets durs).

Titres et en-têtes

Utilisez uniquement le style en-têtes ATX (#, par opposition au style = ou -).

• Utilisation de la casse de phrase : seuls les noms propres et la première lettre d’un titre ou d’un en-tête doivent être en majuscules
• Inclure un espace unique entre la # première lettre du titre
• Entourer les en-têtes avec une seule ligne vide
• N’utilisez pas plus d’un H1 par document
  • Il doit s’agir du premier en-tête
  • Il doit correspondre au titre de l’article
• Incrémenter de un les niveaux d’en-tête, sans ignorer de niveaux
• Limiter la profondeur à H3 ou H4
• Évitez d’utiliser du gras ou d’autres marques de balisage dans les en-têtes

Limiter la longueur de ligne à 100 caractères

Pour les articles conceptuels et les informations de référence sur les applets de commande, limitez les lignes à 100 caractères. Pour about_ les articles, limitez la longueur de ligne à 79 caractères. Limiter la longueur de ligne améliore la lisibilité des git différences et de l'historique. Il facilite également la contribution d’autres écrivains.

Utilisez l’extension Reflow Markdown dans VS Code pour reformater les paragraphes afin qu'ils correspondent à la longueur de ligne prescrite.

Certains types de contenu ne peuvent pas être facilement reflowés. Par exemple, le code à l’intérieur des blocs de code peut également être difficile à redistribuer, en fonction du contenu et du langage de programmation. Vous ne pouvez pas ajuster dynamiquement une table. Dans ces cas, utilisez votre meilleur jugement pour conserver le contenu le plus proche possible de la limite de 100 caractères.

Accentuation

Pour mettre l'accent, Markdown prend en charge les caractères gras et italiques. Markdown vous permet d’utiliser soit * soit _ pour marquer l’accentuation. Toutefois, pour être cohérent et afficher l’intention :

• Utilisez ** pour mettre en gras
• Utiliser _ pour les italiques

En suivant ce modèle, il est plus facile pour d’autres personnes de comprendre l’intention du balisage lorsqu’il existe un mélange de gras et d’italiques dans un document.

Listes

Si votre liste comporte plusieurs phrases ou paragraphes, envisagez d’utiliser un en-tête de sous-niveau plutôt qu’une liste.

Entourez les listes avec une seule ligne vide.

Listes non triées

• Ne terminez pas les éléments de liste avec un point, sauf s’ils contiennent plusieurs phrases.
• Utilisez le caractère trait d’union (-) comme puces des éléments de liste pour éviter toute confusion avec des marques d’accentuation qui utilise l’astérisque (*).
• Pour inclure un paragraphe ou d’autres éléments sous un élément de puce, insérez un saut de ligne et alignez le retrait avec le premier caractère qui se trouve après la puce.

Par exemple:

This is a list that contains child elements under a bullet item.

- First bullet item

  Sentence explaining the first bullet.

  - Child bullet item

    Sentence explaining the child bullet.

- Second bullet item
- Third bullet item

Cette liste contient des éléments enfants sous un élément de puce.

• Premier élément de puce

  Phrase expliquant la première puce.

  • Élément de puce enfant

    Phrase expliquant la puce enfant.

• Deuxième élément de puce

• Troisième élément de puce

Listes triées

• Tous les éléments d’une liste numérotée doivent utiliser le nombre 1. plutôt que d’incrémenter chaque élément.
  • Le rendu Markdown incrémente automatiquement la valeur.
  • Cela facilite la réorganisation des éléments et normalise la mise en retrait du contenu subordonné.
• Pour inclure un paragraphe ou d’autres éléments sous un élément numéroté, alignez la mise en retrait avec le premier caractère après le numéro d’élément.

Par exemple:

1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to
   the next line and must line up with the first character after the numbered list marker.

   To include a second element, insert a line break after the first and align indentations. The
   indentation of the second element must line up with the first character after the numbered list
   marker.

1. The next numbered item starts here.

Le Markdown obtenu est rendu comme suit :

1. Pour le premier élément, insérez un espace unique après le 1. Les phrases longues doivent être encapsulées à la ligne suivante et doivent correspondre au premier caractère après le marqueur de liste numérotée.

   Pour inclure un deuxième élément, insérez un saut de ligne après le premier et alignez les marges. La mise en retrait du deuxième élément doit correspondre au premier caractère après le marqueur de liste numérotée.

2. L’élément numéroté suivant commence ici.

Images

La syntaxe permettant d’inclure une image est la suivante :

![[alt text]](<folderPath>)

Example:
![Introduction](./media/overview/Introduction.png)

Où alt text est une brève description de l’image et <folderPath> est un chemin d’accès relatif à l’image.

• Un texte alternatif est nécessaire pour prendre en charge les lecteurs d’écran pour les personnes malvoyantes.
• Les images doivent être stockées dans un media/<article-name> dossier dans le dossier contenant l’article.
  • Créez un dossier qui correspond au nom de fichier de votre article sous le media dossier. Copiez les images de cet article dans ce nouveau dossier.
• Ne partagez pas d’images entre les articles.
  • Si une image est utilisée par plusieurs articles, chaque dossier doit avoir une copie de cette image.
  • Cela empêche une modification d’une image dans un article d’affecter un autre article.

Les types de fichiers image suivants sont pris en charge : *.png, , *.gif*.jpeg, *.jpg,*.svg

Extension Markdown - Boîtes d’alerte

Le Pack Learn Authoring contient des outils qui prennent en charge les fonctionnalités propres à notre système de publication. Les alertes sont une extension Markdown pour créer des guillemets de bloc qui s’affichent avec des couleurs et des icônes mettant en évidence l’importance du contenu. Les types d’alertes suivants sont pris en charge :

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

Ces alertes ressemblent à ceci sur Microsoft Learn :

Bloc de notes

Remarque

Les informations que l’utilisateur doit remarquer, même en survolant le texte.

Bloc d'astuces

Conseil / Astuce

Informations facultatives pour aider un utilisateur à réussir.

Bloc Important

Important

Informations essentielles requises pour la réussite de l’utilisateur.

Bloc d'avertissement

Avertissement

Conséquences potentielles négatives d’une action.

Bloc d’avertissement

Avertissement

Dangereuses certaines conséquences d’une action.

Extension Markdown : tables

Une table est une disposition des données avec des lignes et des colonnes composées de :

• Une seule ligne d’en-tête
• Ligne délimiteur séparant l’en-tête des données
• Zéro ou plusieurs lignes de données

Chaque ligne se compose de cellules contenant du texte arbitraire séparé par des canaux (|). Une barre verticale de début et de fin est également recommandée pour plus de clarté. Les espaces entre les barres verticales et le contenu de la cellule sont coupés. Les éléments de niveau bloc ne peuvent pas être insérés dans une table. Tout le contenu d’une ligne doit se trouver sur une seule ligne.

La ligne de délimitation se compose de cellules dont le seul contenu est constitué de traits d'union (-) et, éventuellement, d'un deux-points au début ou à la fin (:), ou les deux, pour indiquer respectivement l’alignement à gauche, à droite ou centré.

Pour les petites tables, envisagez plutôt d’utiliser une liste. Les listes sont les suivantes :

• Plus facile à gérer et à lire
• Peuvent être ajustées pour s’adapter à la limite de ligne de 100 caractères
• Plus accessible aux utilisateurs qui utilisent des lecteurs d’écran pour obtenir de l’aide visuelle

Pour plus d’informations, consultez la section Tables de la référence Markdown pour Microsoft Learn.

Liens hypertexte

• Les liens hypertexte doivent utiliser la syntaxe [friendlyname](url-or-path)Markdown .

• Le système de publication prend en charge trois types de liens :

  • Liens URL
  • Liens de fichiers
  • Liens croisés

• Toutes les URL vers des sites web externes doivent utiliser HTTPS, sauf s’il n’est pas valide pour le site cible.

• Les liens doivent avoir un nom convivial, généralement le titre de l’article lié

• Évitez d’utiliser des accents graves, du texte en gras ou d’autres marques à l’intérieur des crochets d’un lien hypertexte.

• Les URL nues peuvent être utilisées quand vous documentez un URI spécifique, mais doivent être délimitées par des accents graves. Par exemple:

  By default, if you don't specify this parameter, the DMTF standard resource URI
  `http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.
  

• Utilisez des références de liens où cela est autorisé. Les références de liens dans les paragraphes rendent les paragraphes plus lisibles.

  Les références de liens divisent un lien Markdown en deux parties :

  • référence de lien - [friendlyname][id]
  • la définition du lien - [id]: url-or-path

Liens de type URL

• Les liens d’URL vers d’autres articles sur learn.microsoft.com devront utiliser des chemins relatifs au site. La façon la plus simple de créer un lien relatif de site consiste à copier l’URL de votre navigateur, puis à supprimer https://learn.microsoft.com/en-us de la valeur que vous collez dans markdown.
• N’incluez pas de paramètres régionaux dans les URL des propriétés Microsoft (retirez /en-us de l'URL) ou des liens Wikipédia.
• Supprimez les paramètres de requête inutiles de l’URL. Exemples à supprimer :
  • ?view=powershell-5.1 - utilisé pour établir un lien vers une version spécifique de PowerShell
  • ?redirectedfrom=MSDN - ajouté à l’URL lorsque vous êtes redirigé à partir d’un ancien article vers son nouvel emplacement
• Si vous devez créer un lien vers une version spécifique d’un document, vous devez ajouter le &preserve-view=true paramètre à la chaîne de requête. Par exemple : ?view=powershell-5.1&preserve-view=true
• Sur les sites Microsoft, les liens d’URL ne contiennent pas d’extensions de fichier (par exemple, non .md)

Liens de type fichier

• Un lien de fichier est utilisé pour lier d’un article de référence à un autre ou d’un article conceptuel à un autre dans le même document.
  • Si vous avez besoin de lier d’un article conceptuel à un article de référence, vous devez utiliser un lien d’URL.
  • Si vous devez créer un lien vers un article d’un autre document ou entre des référentiels, vous devez utiliser un lien d’URL.
• Utiliser des chemins de fichiers relatifs (par exemple : ../folder/file.md)
• Tous les chemins de fichiers utilisent des caractères de barre oblique (/)
• Inclure l’extension de fichier (par exemple, .md)

Liens croisés

Les liens de référence croisée sont une fonctionnalité spéciale prise en charge par le système de publication. Vous pouvez utiliser des liens de référence croisée dans des articles conceptuels pour lier à l’API .NET ou à la référence d’applet de commande.

• Pour obtenir des liens vers les références de l'API .NET, consultez Utiliser des liens dans la documentation dans le guide central du contributeur.

• Les liens vers les références d’applet de commande ont le format suivant : xref:<module-name>.<cmdlet-name>. Par exemple, pour créer un lien vers l’applet Get-Content de commande dans le module Microsoft.PowerShell.Management .

  [Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)

Liaison approfondie

Un lien profond est autorisé à la fois sur les liens d’URL et de fichiers.

• Le texte d’ancrage doit être en minuscules
• Ajoutez l’ancre à la fin du chemin cible. Par exemple:
  • [about_Splatting](about_Splatting.md#splatting-with-arrays)
  • [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

Pour plus d’informations, consultez Utiliser des liens dans la documentation.

Étendues de code

Les étendues de code sont utilisées pour des extraits de code inlined au sein d’un paragraphe. Utilisez des accents graves simples pour indiquer une étendue de code. Par exemple:

PowerShell cmdlet names use the `Verb-Noun` naming convention.

Cet exemple s’affiche sous la forme suivante :

Les noms d’applets de commande PowerShell utilisent la convention d’affectation Verb-Noun de noms.

Blocs de code

Les blocs de code sont utilisés pour les exemples de commandes, les exemples de code multiligne, les langages de requête et les sorties. Il existe deux façons d’indiquer qu'une section de texte dans un fichier d’article est un bloc de code : soit en l'entourant de triple backticks (```), soit en le mettant en retrait.

N’utilisez jamais la mise en retrait, car il est trop facile de se tromper et il peut être difficile pour un autre rédacteur de comprendre votre intention lorsqu’il doit modifier votre article.

Les blocs de code délimités peuvent inclure une balise facultative qui indique la syntaxe de langage contenue dans le bloc. La plateforme de publication prend en charge une liste de balises linguistiques. La balise de langue est utilisée pour fournir la mise en surbrillance de la syntaxe lorsque l’article est rendu sur la page web. La balise de langue n’est pas sensible à la casse, mais vous devez utiliser des minuscules à l’exception de quelques cas spéciaux.

• Les clôtures de code sans balises peuvent être utilisées pour les blocs de syntaxe ou d’autres types de contenu où la mise en surbrillance de la syntaxe n’est pas nécessaire.
• Lorsque vous affichez la sortie d’une commande, utilisez une clôture de code étiquetée avec la balise Outputde langue. La boîte rendue est marquée sous le nom de Output et n’a pas de mise en évidence de la syntaxe.
• Si la sortie se trouve dans une langue prise en charge spécifique, utilisez la balise de langue appropriée. Par exemple, de nombreuses commandes génèrent json. Utilisez donc la json balise.
• Si vous utilisez une balise de langue non prise en charge, le bloc de code s’affiche sans mise en surbrillance de syntaxe. La balise de langue devient l’étiquette de la zone de code rendue sur la page web. Mettre en majuscule la balise afin que l’étiquette soit mise en majuscule sur la page web.

Étapes suivantes

guide de style PowerShell