GitHub Flavored Markdown vs CommonMark : lequel cibler pour votre conversion
Choisissez le mauvais dialecte Markdown pour votre destination et la conversion réussit techniquement pendant que le résultat se rend silencieusement de travers : les tableaux deviennent du texte littéral, le barré affiche ses tildes, les listes à cocher perdent leurs cases. La correction ne coûte rien, mais seulement si vous choisissez avant de convertir.
Ce guide explique ce que CommonMark spécifie réellement, ce que GitHub Flavored Markdown ajoute par-dessus, quelles plateformes parlent quelle saveur, et comment ce choix se concrétise en pratique lorsqu'un convertisseur se place entre vos brouillons Word et leur destination de publication finale.
CommonMark : une spécification pour le cœur de Markdown
Le Markdown classique était un script Perl accompagné d'une description en prose, et dans les années 2010, des dizaines d'implémentations n'étaient pas d'accord sur des cas de base : une liste continue-t-elle après un paragraphe indenté, qu'est-ce qui compte comme emphase à travers les sauts de ligne, quand un nombre suivi d'un point est-il une liste. Le même fichier se rendait différemment presque partout.
CommonMark a répondu par une spécification formelle : une grammaire sans ambiguïté pour la syntaxe centrale de Markdown, des centaines d'exemples de test avec un seul rendu correct chacun, et des implémentations de référence pour vérifier. John MacFarlane, qui écrit aussi pandoc, comptait parmi ses auteurs, et la spécification s'est imposée rapidement.
Aujourd'hui, CommonMark est la couche de base sur laquelle presque tout se construit. Il n'inclut délibérément ni tableaux ni barré ; il ne définit que les fondations sur lesquelles reposent ces fonctionnalités, ce qui est exactement la raison pour laquelle une deuxième couche d'extensions a été nécessaire.
Ce que GFM ajoute par-dessus
GitHub Flavored Markdown, spécifié publiquement en 2017, est un sur-ensemble strict de CommonMark. Ses ajouts sont au nombre de cinq : les tableaux écrits avec des barres verticales, le barré avec des doubles tildes, les éléments de liste de tâches avec cases à cocher, la liaison automatique des URL nues, et un filtre qui empêche l'exécution de certaines balises HTML brutes.
Chaque ajout cible quelque chose que les développeurs écrivaient déjà. Les tableaux à barres couvrent les matrices de dépendances et de tests ; les listes de tâches transforment un README en checklist ; les liens automatiques évitent d'entourer chaque URL de chevrons. Le filtre HTML est une mesure de sécurité, qui retire les balises rendant le HTML embarqué dangereux sur un site où tout le monde peut éditer.
GitHub rend le Markdown via cmark-gfm, un fork de l'implémentation de référence CommonMark avec ces extensions intégrées. GitLab et Gitea suivent la même forme générale, ce qui explique pourquoi GFM se comporte de manière cohérente sur les grandes forges de code au lieu de varier d'un site à l'autre.
Où vit chaque saveur
GFM est chez lui sur GitHub, évidemment, et dans les outils de sites statiques qui l'adoptent par défaut : Hugo rend via un moteur configuré pour GFM dès le départ, et MkDocs active les tableaux d'emblée. Obsidian accepte les trois constructions emblématiques — tableaux à barres, barré et listes de tâches — et ajoute ses propres fonctionnalités de dialecte par-dessus.
Les parseurs CommonMark stricts vivent dans des bibliothèques et des moteurs de blogs qui privilégient délibérément un noyau petit et prévisible. Le Markdown par défaut de pandoc est une troisième saveur à part entière, un vaste sur-ensemble avec tableaux en grille, syntaxe de citations et autres extensions que GitHub ne rend pas.
Rien de tout cela ne rend une saveur meilleure que l'autre. La question n'est jamais de savoir quel dialecte gagne dans l'abstrait, mais quel dialecte votre destination rend réellement, et si le fichier que vous allez produire reste dans cette limite.
Pourquoi les convertisseurs se soucient de la différence
Un convertisseur ne traduit pas seulement la syntaxe, il choisit un dialecte à émettre. C'est avec les tableaux que le choix est le plus visible. Si la cible est GitHub et que le dialecte de sortie prend en charge les tableaux à barres, un tableau simple arrive comme un tableau. Sinon, le même tableau peut retomber sur une syntaxe que la destination ignore, et les lecteurs voient des lignes de texte brut avec des barres verticales dedans.
Le barré et les cases des listes de tâches échouent de la même manière, en plus discret : des tildes restées visibles dans le texte, des crochets de case rendus littéralement. Le document n'est pas corrompu au sens propre, il parle simplement une langue que le moteur de rendu du lecteur ne connaît pas.
C'est aussi pourquoi le format source compte moins qu'on ne le pense. Pandoc analyse l'entrée, qu'il s'agisse de docx ou de CSV, en un modèle de document abstrait, et la décision de dialecte intervient à l'écriture de la sortie. Un reader, de nombreux writers, et le writer est ce que vous contrôlez.
Choisir selon la destination
Pour tout ce qui atterrit sur une forge de code ou dans un coffre, choisissez GFM : les pull requests GitHub, les wikis GitLab, les notes Obsidian et les sites Hugo rendent tous ses constructions. Pour un moteur de blog ou une bibliothèque qui annonce du CommonMark strict, choisissez le CommonMark pur et attendez-vous à ce que les tableaux aient besoin d'un repli HTML ou d'extension.
Quand vous ne connaissez pas la destination, GFM est le défaut le plus sûr. Ses quatre ajouts visibles sont les extensions les plus largement prises en charge du monde Markdown, et les plateformes qui en sautent un dégradent généralement avec grâce plutôt que d'afficher la syntaxe brute.
La seule erreur qui vaille la peine d'être évitée est de supposer qu'un sur-ensemble est toujours sûr. Un fichier écrit en Markdown pandoc avec des tableaux en grille ou une syntaxe de citation semble parfait dans pandoc et casse sur GitHub. Émettre le dialecte de la cible l'emporte toujours sur l'émission d'un dialecte plus riche que la cible ne peut pas analyser.
Ce que l'interrupteur GFM change dans la conversion
Le convertisseur de ce site expose le choix sous la forme d'un unique interrupteur. Avec GFM activé, la sortie Markdown utilise des tableaux à barres, conserve intactes les syntaxes de barré et de listes de tâches, et évite les constructions que GitHub ne rend pas, comme les balises HTML d'image brutes ou les attributs de largeur attachés aux liens.
Sans lui, la sortie suit la saveur Markdown propre à pandoc : toujours parfaitement valide, toujours lisible, mais les tableaux complexes peuvent sortir dans des dialectes que GitHub ignore, et les fonctionnalités au-delà du cœur de CommonMark ne sont pas garanties d'arriver sous leurs formes GFM familières de l'autre côté.
L'interrupteur a aussi une interaction discrète qu'il vaut la peine de connaître : pour les entrées CSV et TSV, le résultat est un document tabulaire, et c'est le mode GFM qui garde ce tableau dans la syntaxe à barres que GitHub rend réellement, plutôt que dans une variante qu'il ignore.
Le cas limite des sauts de ligne
Les sauts de ligne sont la différence qui survit à tous les autres choix. Dans CommonMark, un simple saut de ligne à l'intérieur d'un paragraphe est un saut souple, rendu comme une espace, et il faut deux espaces finales ou une barre oblique inversée pour un saut dur. GFM garde cette règle pour les fichiers.
La réalité est plus désordonnée : les commentaires et corps d'issues GitHub traitent les sauts de ligne simples comme des sauts visibles, et Obsidian fait de même par défaut, sauf si vous activez les sauts de ligne stricts dans les réglages. Un paragraphe coupé au milieu d'une phrase se rend donc d'une façon sur GitHub et d'une autre dans le README à côté.
La règle pratique : écrivez les paragraphes en une seule longue ligne quand la sortie est CommonMark ou GFM, et ne comptez sur le saut-de-ligne-comme-coupure que là où la plateforme vous a dit qu'elle fonctionne ainsi. Tout le reste du choix de dialecte se corrige après coup ; les sauts de ligne sont le seul problème qui se cache en pleine lumière.