Indentation Markdown : listes imbriquées, paragraphes et code
Corrigez l'indentation Markdown avec des exemples de puces imbriquées, listes numérotées, paragraphes de continuation et code délimité. Évitez les blocs de code accidentels.
Pour indenter une sous-liste Markdown, alignez son marqueur sous le premier caractère du texte de l'élément parent. Pour - Parent, cela correspond à deux espaces. Pour 1. Parent, il en faut trois. L'indentation contrôle la structure du document ; ajouter des espaces à un paragraphe normal peut donc avoir un effet très différent du réglage du retrait visuel d'un paragraphe Word.
Commencez par cet exemple dans la visionneuse Markdown :
- Documents du projet
- Guide d'installation
- Notes de version
- Liste de vérification de la relecture
Le guide d'installation et les notes de version doivent apparaître sous l'élément des documents du projet. La liste de vérification de la relecture doit rester au niveau extérieur.
Compter à partir du contenu de l'élément parent
Pour les éléments de liste ordinaires écrits avec une espace après le marqueur, utilisez ce guide d'alignement :
| L'élément parent commence par | Caractères avant son texte | Indentation de la sous-liste |
|---|---|---|
- | 2 | 2 espaces |
1. | 3 | 3 espaces |
12. | 4 | 4 espaces |
100. | 5 | 5 espaces |
C'est pourquoi une règle générale comme « toujours utiliser deux espaces » ne fonctionne pas pour les listes numérotées. La documentation GitHub sur les listes imbriquées montre l'alignement par rapport au contenu parent, y compris avec des marqueurs numériques plus longs.
1. Préparer la publication
- Confirmer le numéro de version.
- Mettre à jour le journal des modifications.
2. Publier la documentation
Les marqueurs imbriqués sont précédés de trois espaces. S'ils commencent à la marge gauche, ils créent une liste distincte au lieu d'appartenir à la première étape numérotée.
Si vous travaillez avec un ancien processeur Markdown, prévisualisez également le fichier dans celui-ci. Les exemples présentés ici visent l'analyse de type CommonMark et GitHub Markdown ; les implémentations anciennes peuvent reconnaître les blocs imbriqués différemment.
Ajouter un paragraphe dans un élément de liste
Une explication plus longue n'a pas besoin de sa propre puce. Laissez une ligne vide, puis alignez le nouveau paragraphe sous le texte de l'élément :
1. Relire le guide d'installation.
Confirmer qu'une nouvelle personne peut terminer la configuration sans
ouvrir de document interne.
2. Approuver les notes de version.
Le paragraphe explicatif appartient à la première étape. Ses deux lignes source s'enchaînent, sauf si vous ajoutez un saut de ligne explicite.
L'absence des trois espaces peut terminer la liste numérotée et transformer l'explication en paragraphe ordinaire. Cela peut aussi faire repartir la numérotation de la liste suivante dans certains flux de travail d'édition.
Le même modèle fonctionne avec des puces :
- Guide d'installation
Inclure les prérequis, les commandes de configuration et une étape de vérification.
- Notes de version
Utilisez un paragraphe séparé lorsque l'explication contient plusieurs phrases. Utilisez une sous-liste lorsqu'elle contient des éléments distincts que les lecteurs doivent pouvoir parcourir individuellement.
Placer du code dans une étape numérotée
Le code délimité rend les limites d'un exemple de commande visibles. Indentez le délimiteur d'ouverture, le contenu et le délimiteur de fermeture pour garder le bloc dans l'élément de liste :
1. Vérifier la version installée.
```sh
node --version
```
Noter le résultat dans les notes de relecture.
2. Exécuter les vérifications du projet.
Ici, le délimiteur commence sous la première lettre de Vérifier. Le paragraphe qui le suit utilise le même alignement et reste donc lui aussi dans la première étape.
Si l'étape numérotée suivante est intégrée au bloc de code, vérifiez le délimiteur de fermeture. Si le code apparaît hors de la liste, vérifiez les espaces avant le délimiteur. Consultez le guide des blocs de code pour les libellés de langage et les accents graves littéraux.
Pourquoi quatre espaces peuvent transformer du texte en code
Au niveau extérieur du document, après une ligne vide, quatre espaces devant une ligne peuvent créer un bloc de code indenté :
Un paragraphe ordinaire.
Cette ligne s'affiche comme du code.
C'est une syntaxe Markdown intentionnelle, pas un réglage de retrait défectueux. La référence CommonMark des blocs de code indentés explique le rôle de l'indentation et des limites de blocs.
Une ligne indentée qui suit immédiatement le texte d'un paragraphe ordinaire est soumise à d'autres contraintes d'analyse ; insérer des espaces n'est donc pas un moyen fiable de créer un retrait visuel de paragraphe. Dans les listes, le nombre d'espaces requis dépend aussi de l'élément contenant le bloc.
Pour une citation, utilisez une citation en bloc. Pour du texte courant nécessitant un retrait de première ligne dans un rapport final, conservez un paragraphe normal en Markdown et appliquez la mise en forme de paragraphe dans Word après l'export. Ces choix préservent le sens prévu du contenu.
Privilégier les espaces lors du débogage
Les tabulations peuvent occuper plusieurs colonnes à l'écran, et les éditeurs peuvent les afficher avec des largeurs différentes. Si une liste semble alignée dans la source mais s'affiche mal, affichez les caractères d'espacement dans votre éditeur et remplacez les tabulations initiales par le nombre d'espaces requis.
Ne remplacez pas sans distinction les tabulations dans les exemples de code. À cet endroit, l'espacement peut faire partie de l'exemple lui-même. Limitez le nettoyage aux marqueurs Markdown et à l'indentation de continuation qui déterminent la structure de la liste environnante.
Évitez de répéter des entités d'espace insécable pour imiter une liste imbriquée. Cela peut donner l'impression que le texte est décalé dans un aperçu tout en laissant le document sous-jacent composé de paragraphes sans relation.
Vérifier la structure avant l'export Word
Examinez une section représentative contenant un élément parent, une sous-liste, un deuxième paragraphe et un bloc de code délimité. Dans le convertisseur Markdown vers HTML, une véritable liste imbriquée est contenue dans son élément de liste parent ; un simple décalage visuel n'établit pas cette relation.
Utilisez ensuite le convertisseur Markdown vers Word et ouvrez le DOCX. Vérifiez que la numérotation se poursuit comme prévu et que les commandes restent associées à leurs étapes. Les styles de liste de Word peuvent utiliser un espacement visuel différent de celui du navigateur ; évaluez donc à la fois la hiérarchie et l'apparence finale du document avant de le partager.