Maîtriser les Listes Markdown : Normes d'Indentation CommonMark & GitHub Flavored Markdown (GFM)
Les Fondements Techniques du Rendu des Listes Markdown
Markdown s'est imposé comme le langage de balisage standard pour la documentation logicielle moderne, les spécifications techniques, les bases de connaissances personnelles et la communication entre développeurs. Bien que les listes à puces simples (- élément) et les listes numérotées (1. élément) semblent simples, la création de plans complexes fortement imbriqués introduit des difficultés de formatage importantes. Différents analyseurs Markdown — tels que CommonMark, GitHub Flavored Markdown (GFM), Python-Markdown et Pandoc — appliquent des règles strictes concernant les puces, les ratios de tabulations en espaces et l'indentation des sous-blocs.
Lorsque des listes sont copiées-collées entre différents éditeurs de texte (comme VS Code, Sublime Text, Xcode, Apple Notes ou Microsoft Word), des erreurs d'indentation invisibles surviennent. Un seul espace manquant sur un sous-élément amène le compilateur Markdown à interpréter un nœud enfant imbriqué comme un élément principal ou un paragraphe isolé. Le Formateur de Listes Imbriquées & Indentation d'Utiliome élimine ces anomalies en analysant l'arbre syntaxique abstrait (AST) de votre texte et en régénérant un code Markdown standardisé et conforme aux spécifications.
Règles d'Indentation : Directives 2 Espaces vs. 4 Espaces
L'un des débats les plus fréquents en documentation technique est de savoir s'il faut indenter les sous-listes avec 2 ou 4 espaces par niveau hiérarchique. Le choix dépend de la spécification de l'analyseur Markdown ciblé :
La Règle d'Indentation à 2 Espaces (Standard GFM & Prettier) : Dans les écosystèmes modernes de documentation web comme GitHub, Docusaurus, Nextra et Obsidian, 2 espaces par niveau constituent la norme reconnue. La convention à 2 espaces aligne le contenu enfant sous le début du texte de l'élément parent :
- Élément principal 1 - Sous-élément imbriqué 1.1 - Sous-élément imbriqué 1.2 - Sous-sous-élément profondément imbriqué 1.2.1 - Élément principal 2La Règle d'Indentation à 4 Espaces (CommonMark Stricte & Python-Markdown) : Les implémentations strictes de CommonMark exigent que les blocs enfants, extraits de code et listes imbriquées dans des listes ordonnées soient indentés de 4 espaces (ou 1 tabulation complète) pour garantir la bonne inclusion dans le bloc parent :
1. Première étape ordonnée du flux de travail - Sous-puce associée A - Sous-puce associée B 2. Deuxième étape ordonnée du flux de travailPièges des Tabulations vs. Espaces : Mélanger des caractères de tabulation (
\t) avec des espaces ASCII (\x20) est la principale cause d'erreur d'affichage de la documentation Markdown. Les moteurs de rendu web interprètent les tabulations de manière inconstante (souvent 4 ou 8 colonnes), provoquant des décalages visuels. Utiliome convertit automatiquement toutes les tabulations en chaînes d'espaces uniformes selon vos préférences.
Normalisation des Puces & Correction des Séquences Ordonnées
Markdown prend en charge trois caractères de puces distincts pour les listes non ordonnées : les tirets (-), les astérisques (*) et les signes plus (+). Bien que tous trois génèrent des éléments HTML de liste non ordonnée valides (<ul>), mélanger ces symboles au sein d'un même document crée un désordre visuel et échoue aux contrôles de linters (comme la règle MD004 de markdownlint).
De plus, la numérotation des listes ordonnées est souvent altérée lors des éditions successives. Les auteurs collent fréquemment des éléments au milieu de séquences numérotées ou s'appuient sur la syntaxe d'auto-incrémentation 1. :
<!-- Entrée non formatée / cassée -->
* Fonctionnalité A
- Fonctionnalité B
+ Fonctionnalité C
1. Étape initiale
1. Deuxième étape (copiée du brouillon)
4. Étape hors ordre
Le formateur Utiliome normalise toutes les puces de listes non ordonnées vers le caractère unique que vous avez choisi (par exemple en convertissant chaque élément avec -) et renumérote les séquences ordonnées de manière séquentielle (1., 2., 3.) ou standardise les incréments (1., 1., 1.) selon les conventions de votre équipe.