GFM vs CommonMark vs Pandoc Markdown : comparaison des syntaxes

La syntaxe Markdown ressemble à un seul langage jusqu’à ce que le même fichier s’affiche différemment sur GitHub, Hugo, Obsidian ou Pandoc. Le problème n’est pas que Markdown soit peu fiable.

C’est que « Markdown » décrit une famille de syntaxes, d’analyseurs et de fonctionnalités de plateforme apparentées, plutôt qu’un format de document universel unique. CommonMark définit un noyau portable précis, GitHub Flavored Markdown ajoute des fonctionnalités utiles pour la collaboration logicielle, et Pandoc Markdown étend le langage vers un format sérieux d’aide à la rédaction de documents.

Le choix entre eux dépend de l’endroit où le document doit être rendu. Un fichier README, un article de blog Hugo et un article académique ont chacun des exigences différentes. Cette comparaison fait partie du panorama plus large des outils de documentation et couvre les dialectes formels, les extensions spécifiques à la plateforme et les règles de portabilité pratiques afin que vous puissiez choisir la bonne syntaxe pour votre environnement cible. Pour une référence syntaxique rapide, la cheat sheet Markdown couvre les éléments de mise en forme essentiels.

Markdown n’est pas un seul langage

La syntaxe Markdown originale était intentionnellement petite et spécifiquement de manière lâche. Cela a facilité la lecture et l’implémentation, mais différents analyseurs ont commencé à interpréter les entrées ambiguës différemment.

CommonMark a été créé pour définir des règles d’analyse cohérentes pour les structures fondamentales de Markdown. GitHub Flavored Markdown, souvent appelé GFM, s’appuie sur cette base avec plusieurs extensions largement utilisées.

Pandoc Markdown adopte une approche différente. Au lieu de rester une syntaxe orientée web, il ajoute des fonctionnalités de document telles que les citations, les métadonnées, les notes de bas de page, les listes de définition, les attributs et la notation mathématique.

Une relation simplifiée ressemble à ceci :

Cette hiérarchie est utile, mais ce n’est pas une héritage exact dans chaque implémentation. Chaque moteur de rendu peut activer, désactiver ou ajouter de la syntaxe indépendamment.

La réponse courte

Utilisez la syntaxe compatible CommonMark lorsque la portabilité est la plus importante.

Utilisez GFM pour écrire des fichiers README, des pull requests, des modèles de problèmes et de la documentation technique destinée principalement aux plateformes compatibles GitHub.

Utilisez Pandoc Markdown lorsque le document source doit devenir un PDF, DOCX, EPUB, LaTeX, des diapositives ou un article académique avec citations et métadonnées.

Pour un blog technique Hugo, utilisez le noyau CommonMark plus les extensions Goldmark que votre site active explicitement. Ne supposez pas que chaque fonctionnalité visible sur GitHub fonctionnera simplement parce que Hugo est décrit comme compatible GFM.

Point de vue personnel : si vous ne retenez qu’une seule règle pour un blog technique Hugo, considérez CommonMark plus les tableaux et listes de tâches de style GFM comme la valeur par défaut, et traitez tout le reste — notes de bas de page, mathématiques, encadrés, attributs d’en-tête — comme une extension explicite et testée plutôt que comme une valeur par défaut supposée. Cette seule habitude empêche la plupart des échecs de portabilité décrits ci-dessous.

CommonMark : Le noyau portable

CommonMark est une spécification formelle pour le langage Markdown de base. Sa principale contribution n’est pas une grande collection de fonctionnalités, mais une analyse cohérente.

Il définit comment les analyseurs doivent interpréter :

• Les paragraphes
• Les titres ATX et Setext
• Les citations en bloc
• Les listes ordonnées et non ordonnées
• Les blocs de code clôturés et indentés
• L’ emphase et l’ emphase forte
• Les liens et les images
• Les liens de style référence
• Le code en ligne
• Les ruptures thématiques
• Les blocs HTML bruts
• Les retours à la ligne durs et mous

Un document CommonMark peut encore se comporter différemment au niveau de la présentation. Le CSS, la coloration syntaxique, les ancres de titres, la sanitisation HTML et les politiques de liens sont hors des règles d’analyse du noyau.

CommonMark doit donc être traité comme une base structurelle fiable, et non comme une promesse que chaque moteur de rendu produira une page identique.

Exemple de CommonMark portable

# Déploiement du service

Le service expose une petite API HTTP.

## Exigences

- Linux
- Docker
- 8 Go de mémoire

## Démarrer le service

```bash
docker compose up -d
```

Voir le [guide de configuration](configuration.md) pour plus de détails.

Ce type de document fonctionne dans presque tous les environnements Markdown modernes. Il utilise des titres, des paragraphes, des listes, du code clôturé et des liens ordinaires sans s’appuyer sur des extensions spécifiques au dialecte.

GitHub Flavored Markdown : CommonMark pour les projets logiciels

GitHub Flavored Markdown est un dialecte formel basé sur CommonMark. Il préserve le modèle d’analyse de CommonMark et ajoute des fonctionnalités couramment nécessaires dans la documentation des dépôts et la collaboration.

La spécification formelle GFM ajoute :

• Les tableaux avec des barres verticales
• Les éléments de liste de tâches
• Le texte barré
• Les autoliens étendus
• Des restrictions autour de certaines balises HTML brutes

Ces extensions sont maintenant si courantes que de nombreux utilisateurs pensent qu’elles font partie du Markdown standard. Elles ne font pas partie du noyau CommonMark.

Tableaux GFM

| Backend | Meilleure utilisation |
|---|---|
| Ollama | Expériences locales |
| vLLM | Inférence partagée |
| SGLang | Charges de travail structurées |

Un analyseur CommonMark strict est autorisé à traiter cela comme du texte de paragraphe ordinaire. Un analyseur compatible GFM le reconnaît comme un tableau. Pour un regard plus approfondi sur la syntaxe des tableaux et les options d’alignement, voir Tableaux en Markdown.

Listes de tâches GFM

- [x] Installer Docker
- [x] Télécharger le modèle
- [ ] Ajouter la surveillance

La syntaxe des listes de tâches est utile dans les problèmes, les pull requests et la documentation de projet. En dehors d’un moteur de rendu supportant, elle peut apparaître comme une liste ordinaire contenant des crochets littéraux.

Texte barré GFM

Utiliser l'~~ancienne borne~~ nouvelle borne.

Le texte barré est largement supporté, mais c’est toujours une extension plutôt qu’une syntaxe CommonMark portable.

Autoliens GFM

GFM reconnaît plus de texte ressemblant à des URL et des emails sans nécessiter de chevrons ou de syntaxe de lien explicite.

Visitez https://example.com/docs pour plus de détails.

Dans CommonMark strict, les autoliens explicites utilisent des chevrons :

<https://example.com/docs>

La forme explicite est plus sûre lorsqu’un document doit traverser des processeurs Markdown inconnus.

GitHub.com supporte plus que le GFM formel

Une source fréquente de confusion est l’hypothèse que chaque fonctionnalité Markdown visible sur GitHub appartient à la spécification GFM.

Ce n’est pas le cas.

GitHub.com ajoute un traitement et des fonctionnalités au niveau de la plateforme autour de l’analyseur GFM. Selon le contexte, GitHub peut supporter :

• Des expressions mathématiques
• Des diagrammes Mermaid
• Des alertes
• Des références aux problèmes et pull requests
• Des mentions d’utilisateurs et d’équipes
• Des références aux commits
• Des shortcodes emoji
• Des sections HTML rétractables
• Des aperçus de couleur
• Des liens relatifs au dépôt
• Des ancres de titres automatiques

Certaines de ces fonctionnalités sont des extensions de syntaxe. D’autres sont un comportement de post-traitement ou des intégrations avec les données GitHub.

Cette distinction est importante car un autre moteur de rendu peut prétendre avec justesse être compatible GFM sans implémenter le moteur mathématique de GitHub, l’intégration Mermaid, les références aux problèmes ou le style des alertes.

Diagrammes Mermaid GitHub

GitHub rend un bloc de code clôturé marqué mermaid comme un diagramme :

```mermaid
flowchart LR
    A[Markdown] --> B[Diagramme rendu]
```

Un moteur de rendu GFM générique peut afficher le même bloc comme du code source coloré. Le Markdown reste valide, mais le rendu amélioré est spécifique à la plateforme. Pour une introduction pratique à la syntaxe Mermaid, voir le Début rapide des diagrammes Mermaid.

Expressions mathématiques GitHub

GitHub supporte les expressions mathématiques en ligne et en bloc en utilisant des délimiteurs dollar et des formes d’échappement supplémentaires.

La taille du cache est d'environ $2nlhd$ octets.

$$
C = 2nlhd
$$

Les mathématiques ne font pas partie du GFM formel. Le déplacement de ce contenu vers un autre moteur de rendu nécessite une extension mathématique compatible telle que KaTeX, MathJax ou le support mathématique de Pandoc.

Alertes GitHub

GitHub supporte des citations en bloc de style alerte telles que :

> [!WARNING]
> Changer ce paramètre efface le cache.

Sur GitHub, cela peut apparaître comme un avertissement stylisé. Sur un moteur de rendu CommonMark simple, il apparaît généralement comme une citation en bloc ordinaire contenant [!WARNING].

Cette régression est lisible, ce qui rend les alertes GitHub moins dangereuses que les extensions qui disparaissent complètement. Elles ne sont toujours pas des éléments de présentation portables.

Pandoc Markdown : Markdown comme langage de document

Pandoc Markdown est conçu pour la conversion de documents plutôt que pour un site web particulier. Il utilise Markdown comme syntaxe source pour produire du HTML, PDF, DOCX, EPUB, LaTeX, des présentations et d’autres formats.

Son lecteur Markdown par défaut inclut un grand ensemble d’extensions. Les capacités importantes incluent :

• Les blocs de métadonnées YAML
• Les notes de bas de page
• Les citations
• Plusieurs formats de tableau
• Les listes de définition
• La notation mathématique
• Les identifiants et attributs d’en-tête
• Les attributs de bloc de code
• Les divisions clôturées
• Les spans bracketés
• Les exposants et indices
• Le texte barré
• Les blocs de lignes
• Les listes d’exemples numérotées
• Le LaTeX brut
• Le HTML brut
• La numérotation automatique des sections
• Le traitement des bibliographies

Pandoc Markdown est beaucoup plus expressif que CommonMark ou le GFM formel. Cette expressivité le rend puissant pour la publication, mais moins sûr en tant que format d’échange.

Notes de bas de page Pandoc

Markdown a plusieurs dialectes incompatibles.[^dialectes]

[^dialectes]: CommonMark, GFM et Pandoc Markdown sont trois
    exemples importants.

La syntaxe des notes de bas de page est supportée par de nombreux outils modernes, mais elle ne fait pas partie de CommonMark ou du GFM formel.

GitHub rend actuellement les notes de bas de page dans plusieurs contextes de contenu, mais c’est une fonctionnalité de la plateforme GitHub plutôt qu’une garantie formelle GFM. Un moteur de rendu prétendant seulement une compatibilité CommonMark ou GFM peut ne pas les supporter.

Citations Pandoc

PagedAttention améliore la gestion de la mémoire du cache KV
[@kwon2023pagedattention].

Avec un fichier de bibliographie et un style de citation, Pandoc peut résoudre cela en une citation académique formatée et une bibliographie.

pandoc article.md \
  --citeproc \
  --bibliography references.bib \
  --csl ieee.csl \
  -o article.pdf

La syntaxe de citation reste lisible dans un moteur de rendu non supporté, mais elle ne deviendra pas une référence formatée sans Pandoc ou un autre processeur de citation compatible. La flexibilité côté lecteur de Pandoc soutient également les flux de travail de conversion dans l’autre sens — voir conversion de documents Word en Markdown pour un exemple pratique d’utilisation du dialecte étendu de Pandoc comme format intermédiaire.

Listes de définition Pandoc

CommonMark
: Une spécification précise pour le Markdown de base.

GFM
: Un dialecte basé sur CommonMark avec des extensions orientées logiciel.

Pandoc Markdown
: Un format d'auteur étendu pour la conversion de documents.

Les listes de définition sont utiles dans les manuels, les glossaires et les livres techniques. Elles se dégradent normalement mal dans les moteurs de rendu qui ne les supportent pas car les lignes de deux-points restent visibles comme du texte brut.

Attributs d’en-tête Pandoc

## Configuration du cache {#cache-config .deployment}

Pandoc interprète les accolades comme un identifiant et une liste de classes explicites. De nombreux autres moteurs de rendu Markdown affichent le texte de l’attribut directement dans l’en-tête.

C’est l’un des exemples les plus clairs de syntaxe utile qui ne devrait pas être placée dans un document censé être rendu partout.

Divisions clôturées Pandoc

::: warning
Changer cette option redémarre le serveur.

Pandoc convertit cela en une division structurelle avec une classe. Les modèles, le CSS, les filtres ou les générateurs de sortie peuvent décider comment cette structure doit apparaître.

La plupart des moteurs de rendu CommonMark et GFM ne reconnaissent pas la clôture. Ils affichent les deux-points et le contenu comme du texte ordinaire.

CommonMark vs GFM vs Pandoc Markdown

La matrice suivante décrit les dialectes formels, pas chaque fonctionnalité ajoutée par GitHub.com, Hugo, Obsidian, GitLab ou une autre plateforme.

Le mot « Non » ne signifie pas qu’une plateforme ne peut jamais supporter la fonctionnalité. Cela signifie que la fonctionnalité n’est pas garantie par la spécification formelle de ce dialecte.

Quelle syntaxe fonctionne sur GitHub ?

Pour les fichiers README, les problèmes, les pull requests, les discussions et les wikis, GFM est la baseline naturelle.

Vous pouvez généralement utiliser :

• La syntaxe CommonMark
• Les tableaux
• Les listes de tâches
• Le texte barré
• Les autoliens étendus
• Les clôtures de code avec coloration syntaxique
• Les références spécifiques à GitHub
• Les mathématiques supportées par GitHub
• Les diagrammes supportés par GitHub
• Les alertes GitHub
• Les notes de bas de page là où elles sont supportées par la surface de contenu

Le risque de portabilité commence lorsque GitHub effectue un rendu supplémentaire au-delà du GFM formel. Les diagrammes Mermaid, la notation mathématique, les références aux problèmes et la présentation des alertes peuvent ne pas survivre en dehors de GitHub.

Pour les fichiers de dépôt qui sont également publiés ailleurs, testez la source dans le deuxième moteur de rendu plutôt que de traiter l’aperçu GitHub comme autoritaire.

Quelle syntaxe fonctionne dans Hugo ?

Hugo utilise Goldmark comme moteur de rendu Markdown par défaut. Goldmark se conforme à CommonMark et fournit des extensions compatibles avec des parties importantes de GFM.

Dans une configuration Hugo typique, les éléments suivants fonctionnent bien :

• La structure CommonMark
• Les blocs de code clôturés
• Les tableaux avec barres verticales
• Le texte barré
• Les listes de tâches
• Les IDs d’en-tête automatiques
• La coloration syntaxique
• Les notes de bas de page lorsque l’extension est activée
• Les listes de définition lorsque activées
• Les substitutions typographiques lorsque activées

Hugo ajoute également des fonctionnalités hors Markdown à travers :

• Le front matter
• Les shortcodes
• Les hooks de rendu
• Les ressources de page
• Les fonctions de référence interne
• Le traitement des templates
• La configuration du site

Ces fonctionnalités Hugo ne voyagent pas avec le fichier Markdown. Pour un exemple pratique de déploiement Hugo, voir Déployer Hugo sur AWS S3.

Le front matter Hugo n’est pas du contenu Markdown

Une page Hugo commence communément avec des métadonnées YAML, TOML ou JSON :

---
title: "Compatibilité Markdown"
description: "Comparer les dialectes et moteurs de rendu Markdown."
date: 2026-07-31
tags:
  - Markdown
  - documentation
---

Pandoc peut également reconnaître les blocs de métadonnées YAML, mais il interprète les champs selon ses propres modèles et générateurs. GitHub affiche normalement le bloc comme une section semblable à YAML ou le traite comme des métadonnées de dépôt uniquement dans des systèmes spécifiques.

La même syntaxe peut donc être reconnue dans plus d’un outil sans avoir la même sémantique.

HTML brut dans Hugo

Goldmark ne rend pas le HTML brut potentiellement non sécurisé par défaut dans une configuration Hugo standard.

Un bloc tel que :

<div class="notice">
  Redémarrez le service après avoir changé cette valeur.
</div>

peut être omis sauf si le rendu HTML brut est activé ou que le contenu est implémenté à travers un shortcode ou un hook de rendu.

Pour un blog technique contrôlé, activer le HTML brut peut être raisonnable. Cela rend toujours la source moins portable et devrait être une décision délibérée au niveau du site.

Mermaid dans Hugo

Un bloc clôturé mermaid n’est toujours qu’un bloc de code à moins que le thème Hugo, le hook de rendu, le shortcode ou le pipeline JavaScript ne le transforme en diagramme.

GitHub et Hugo peuvent donc accepter une source Mermaid identique tout en utilisant des mécanismes de rendu complètement différents.

Quelle syntaxe fonctionne dans Pandoc ?

Pandoc peut lire plusieurs dialectes Markdown explicitement :

pandoc --from=markdown input.md
pandoc --from=commonmark input.md
pandoc --from=gfm input.md
pandoc --from=commonmark_x input.md

C’est l’une des fonctionnalités de portabilité les plus utiles de Pandoc. L’opérateur peut dire à Pandoc quel dialecte la source prétend utiliser au lieu de s’appuyer sur une extension de fichier .md vague.

Pandoc vous permet également d’activer ou de désactiver des extensions individuelles :

pandoc \
  --from=markdown-footnotes-pipe_tables \
  input.md \
  -o output.html

Ou partir d’un format plus étroit et ajouter une fonctionnalité :

pandoc \
  --from=commonmark+footnotes \
  input.md \
  -o output.html

Vous pouvez inspecter les extensions disponibles avec :

pandoc --list-extensions=markdown
pandoc --list-extensions=commonmark
pandoc --list-extensions=gfm

Ce modèle d’extension est puissant, mais cela signifie que « Pandoc Markdown » n’est pas toujours une configuration fixe. Les commandes de build et les fichiers de défauts font partie de la spécification du document.

Quelle syntaxe fonctionne dans Obsidian ?

Obsidian stocke les notes comme des fichiers Markdown, mais son modèle d’auteur inclut plusieurs fonctionnalités spécifiques à l’application.

Des exemples courants incluent :

• Les liens Wiki
• Les notes intégrées
• Les fichiers intégrés
• Les encadrés (callouts)
• Les références de bloc
• Les tags
• Les propriétés
• Le surbrillance
• Les commentaires
• Les requêtes Dataview des plugins
• Les liens URI spécifiques à l’application

Un lien Wiki tel que :

[[Compatibilité Markdown]]

est significatif à l’intérieur d’un coffre Obsidian. GitHub, CommonMark et un lecteur Pandoc par défaut l’affichent normalement comme du texte en double crochets littéral.

Une intégration est encore plus spécifique à l’application :

![[tableau-compatibilite]]

Le contenu référencé n’est pas présent dans le fichier lui-même. L’exportation ou la publication de la note nécessite donc une étape d’expansion qui résout l’intégration.

Obsidian est un bon exemple de pourquoi le stockage dans des fichiers .md ne garantit pas la portabilité Markdown. Pour un regard pratique sur Obsidian en tant qu’outil de gestion des connaissances, voir Obsidian pour la gestion des connaissances personnelles.

Quelle syntaxe fonctionne dans GitLab ?

GitLab Flavored Markdown utilise CommonMark comme noyau et inclut des fonctionnalités GFM telles que les tableaux et les listes de tâches. Il ajoute ensuite un comportement spécifique à GitLab incluant les références croisées, la notation mathématique, les diagrammes et d’autres fonctionnalités de collaboration.

Un README écrit en GFM conservateur se déplace généralement entre GitHub et GitLab sans dommage majeur.

Les intégrations de plateforme ne voyagent pas aussi fiablement. Les références aux problèmes, les mentions d’utilisateurs, les diagrammes, le traitement des mathématiques et la syntaxe de bloc spéciale peuvent se comporter différemment même lorsque le Markdown de base reste lisible.

Matrice de support de la plateforme

Cette matrice décrit le comportement par défaut commun. Les thèmes, plugins, extensions et configurations peuvent changer des cellules individuelles.

« Oui » ne garantit toujours pas un HTML ou une présentation visuelle identique. Cela signifie que l’environnement reconnaît la fonctionnalité générale.

Syntaxe qui est généralement sûre partout

Le sous-ensemble portable le plus sûr inclut :

• Les titres ATX utilisant #
• Les paragraphes ordinaires
• Les lignes vides entre les blocs
• - pour les listes non ordonnées
• 1. pour les listes ordonnées
• Les blocs de code clôturés utilisant des backticks
• Le code en ligne utilisant des backticks
• L’ emphase utilisant *texte*
• L’ emphase forte utilisant **texte**
• Les liens ordinaires
• Les images ordinaires
• Les citations en bloc
• Les ruptures thématiques
• Les autoliens explicites avec chevrons

Un document intentionnellement conservateur pourrait ressembler à ceci :

# Guide de déploiement

Ce guide explique comment déployer le service.

## Exigences

- Docker
- Linux
- Un GPU supporté

## Configuration

Créez un fichier nommé `compose.yaml`.

```yaml
services:
  application:
    image: example/application:1.0
```

Pour plus d'informations, voir la [référence de configuration](config.md).

> Sauvegardez les données existantes avant de mettre à jour.

Cette syntaxe voyage bien car elle ne dépend pas de tableaux, notes de bas de page, attributs, encadrés ou traitement de plateforme.

Syntaxe qui casse communément

Les problèmes de portabilité ont tendance à se regrouper autour d’un petit nombre de fonctionnalités.

Tableaux avec barres verticales

Les tableaux avec barres verticales sont bien supportés par les outils orientés GFM, mais pas par CommonMark strict.

Un tableau peut se dégrader en texte illisible lorsqu’il passe à travers un analyseur qui ne le reconnaît pas. Pour des documents hautement portables, envisagez des listes courtes ou du HTML sémantique généré pendant une étape de build.

Notes de bas de page

La syntaxe des notes de bas de page est devenue courante, mais elle reste une extension.

Différents outils peuvent :

• Supporter uniquement un format de note de bas de page
• Placer les notes de bas de page différemment
• Générer des identifiants différents
• Rejeter les notes de bas de page multi-paragraphes
• Rendre la source littéralement

Utilisez les notes de bas de page lorsque le pipeline de publication est connu. Évitez de dépendre d’elles dans les fichiers README qui doivent être rendus à travers des systèmes arbitraires.

IDs et attributs d’en-tête

Cette syntaxe Pandoc n’est pas portable :

## Installation {#installation .procedure}

Utilisez un en-tête ordinaire et laissez le moteur de rendu générer sa propre ancre lorsque la portabilité est importante.

Évitez également de coder en dur des liens vers des IDs d’en-tête auto-générés sauf si chaque cible utilise les mêmes règles de slugification.

Encadrés et alertes

GitHub, Obsidian, GitLab, MkDocs, Docusaurus et les thèmes Hugo peuvent tous supporter des blocs semblables à des encadrés, mais ils utilisent souvent une syntaxe différente.

Une régression portable est une citation en bloc ordinaire :

> Avertissement : Sauvegardez la base de données avant de mettre à jour.

C’est moins impressionnant visuellement, mais cela préserve le sens partout.

Liens Wiki

Les liens Wiki sont concis à l’intérieur des outils de gestion des connaissances :

[[Cache KV]]

Ils sont une mauvaise syntaxe d’échange car le chemin cible, le nom de fichier, les règles d’en-tête et le comportement de résolution appartiennent à l’application.

Utilisez des liens Markdown standards dans le contenu destiné à la publication :

[Cache KV](cache-kv.md)

HTML brut

Le HTML brut est la valve de décompression habituelle lorsque Markdown ne peut pas exprimer une mise en page. C’est aussi un échec courant de portabilité et de sécurité.

Un moteur de rendu peut :

• Supprimer le HTML
• L’échapper
• Sanitiser des éléments sélectionnés
• Autoriser les blocs mais pas les éléments en ligne
• Refuser l’analyse Markdown à l’intérieur du HTML
• Le passer inchangé uniquement en mode de confiance

Utilisez le HTML brut uniquement lorsque la cible de publication est contrôlée.

Notation mathématique

Les mathématiques délimitées par des dollars sont populaires mais pas universellement interprétées.

La source :

La complexité est $O(n^2)$.

peut devenir :

• Des mathématiques rendues
• Du texte ordinaire avec des signes dollar
• Une emphase incorrecte
• Une entrée pour un analyseur mathématique différent

Choisissez un pipeline mathématique et testez-le dans chaque environnement cible.

Mermaid et autres blocs de diagramme

Une clôture de code Mermaid est syntaxiquement sûre car les moteurs de rendu non supportés l’affichent normalement comme du code.

Le résultat sémantique est toujours différent. Les lecteurs peuvent voir un diagramme d’architecture rendu sur GitHub et la source Mermaid brute dans un autre environnement.

C’est une dégradation gracieuse, pas une vraie compatibilité.

Les trois couches de compatibilité Markdown

Il est utile de séparer la compatibilité en trois couches.

Couche 1 : Compatibilité d’analyse

L’analyseur reconnaît-il la structure ?

Les exemples incluent les titres, les tableaux, les notes de bas de page et les divisions clôturées.

Couche 2 : Compatibilité de transformation

La plateforme applique-t-elle un traitement supplémentaire ?

Les exemples incluent :

• Le rendu Mermaid
• La résolution des citations
• L’expansion des liens Wiki
• Le lien des numéros de problème
• Le traitement des shortcodes
• La génération d’une table des matières

Couche 3 : Compatibilité de présentation

Le résultat a-t-il l’air et se comporte-t-il de manière appropriée ?

Les exemples incluent :

• Le style des tableaux
• La coloration syntaxique
• Les couleurs des alertes
• Les ancres de titres
• Les images responsives
• Le placement des notes de bas de page
• Les polices mathématiques

Deux plateformes peuvent analyser une syntaxe identique tout en produisant une présentation substantiellement différente.

Un meilleur modèle de portabilité

Au lieu de demander si un fichier est « Markdown valide », posez quatre questions plus étroites :

1. Dans quel dialecte la source est-elle écrite ?
2. Quel analyseur la lit ?
3. Quelles extensions sont activées ?
4. Quelles transformations de plateforme s’exécutent ensuite ?

Par exemple :

Dialecte : CommonMark plus tableaux GFM
Analyseur : Goldmark
Extensions : tableaux, texte barré, listes de tâches, notes de bas de page
Plateforme : Hugo
Traitement supplémentaire : hooks de rendu et JavaScript Mermaid

Cette description est beaucoup plus utile que de dire « le site utilise Markdown ».

Choisir un dialecte par cas d’utilisation

Fichiers README

Utilisez GFM.

Les fichiers README bénéficient de :

• Tableaux
• Listes de tâches
• Code clôturé
• Autoliens
• Texte barré
• Références GitHub

Évitez une dépendance excessive aux fonctionnalités uniquement GitHub lorsque le dépôt est miroité sur GitLab, rendu sur un registre de package ou inclus dans la documentation générée.

Articles techniques Hugo

Utilisez du Markdown compatible CommonMark avec un ensemble documenté d’extensions Goldmark.

Les tableaux, clôtures de code, notes de bas de page et Mermaid peuvent être raisonnables car vous contrôlez le pipeline de build. Privilégiez les shortcodes Hugo ou les hooks de rendu plutôt que d’intégrer de grandes quantités de HTML brut.

Gardez la syntaxe spécifique à Hugo isolée et facile à trouver.

Documents académiques

Utilisez Pandoc Markdown.

Les citations, le traitement des bibliographies, les notes de bas de page, les métadonnées, la notation mathématique, les références croisées et la conversion en PDF ou DOCX justifient la portabilité réduite.

Stockez la commande Pandoc, le fichier de défauts, les filtres, la bibliographie et les modèles à côté de la source. Le fichier source seul ne décrit pas entièrement le build.

Livres et documentation longue

Pandoc Markdown est généralement le plus fort des trois options lorsque plusieurs formats de sortie sont importants.

Les listes de définition, les citations, les attributs, les métadonnées et les transformations structurées deviennent plus importantes à mesure que la complexité du document augmente.

Pour la documentation web-only hébergée dans un dépôt Git, GFM ou un générateur de documentation basé sur CommonMark peut rester plus simple.

Notes et bases de connaissances personnelles

Utilisez la syntaxe native de l’application de notes sélectionnée lorsque les fonctionnalités de l’application fournissent une valeur réelle.

Les liens Wiki, intégrations et encadrés Obsidian sont utiles à l’intérieur d’un coffre. Traitez l’exportation comme un processus de compilation plutôt que de supposer que les fichiers bruts sont déjà des publications portables.

Documentation partagée à travers des systèmes inconnus

Utilisez un sous-ensemble CommonMark conservateur.

Évitez :

• Liens Wiki
• Alertes de plateforme
• Attributs d’en-tête
• Citations
• HTML brut
• Conteneurs personnalisés
• Intégrations d’application
• Shortcodes

La portabilité nécessite généralement d’abandonner les fonctionnalités de commodité.

Règles pratiques pour un Markdown portable

Commencer avec la structure CommonMark

Utilisez CommonMark pour le squelette du document :

• Titres
• Paragraphes
• Listes
• Liens
• Images
• Citations en bloc
• Blocs de code

Cela garantit que le sens principal survit même lorsque les extensions optionnelles échouent.

Ajouter les fonctionnalités GFM délibérément

Les tableaux et les listes de tâches sont raisonnables lorsque toutes les cibles importantes les supportent.

Ne supposez pas « la plupart des outils supportent GFM » sans tester la cible exacte. Certains prétendent à la compatibilité GFM tout en n’activant que des extensions sélectionnées.

Isoler les extensions de plateforme

Gardez la syntaxe spécifique à la plateforme dans des blocs clairement identifiables.

Par exemple, centralisez les shortcodes Hugo, les citations Pandoc ou les intégrations Obsidian plutôt que de les disperser à travers chaque paragraphe.

L’isolation rend la conversion ultérieure plus facile.

Privilégier la dégradation gracieuse

Un bloc Mermaid se dégrade en code source lisible. Une alerte GitHub se dégrade en une citation en bloc.

Une intégration Wiki peut se dégrader en un nom de fichier inexpliqué, tandis qu’une division clôturée Pandoc peut exposer la ponctuation autour du contenu.

Choisissez des extensions dont la régression reste compréhensible.

Ne pas dépendre des IDs d’en-tête auto-générés

Les algorithmes d’ancre de titre diffèrent entre GitHub, Hugo, Pandoc et les générateurs de documentation.

Pour les liens croisés entre documents, utilisez des IDs explicifs supportés par le moteur de rendu uniquement lorsque le pipeline cible est contrôlé. Sinon, liez vers le document plutôt que vers un fragment généré.

Garder la configuration de build avec le contenu

Les extensions Pandoc, les paramètres Hugo, les plugins, les filtres et les intégrations JavaScript déterminent comment Markdown se comporte.

Committez les fichiers de configuration pertinents avec la source :

content/
  article.md
pandoc.yaml
references.bib
config/
  _default/
    markup.yaml
layouts/
  _default/
    _markup/

Une extension .md seule ne capture pas l’environnement de publication. Pour une approche structurée de documentation de ces décisions, voir Registres de décision pour le développement piloté par IA.

Tester le Markdown contre chaque cible importante

L’aperçu visuel dans un seul éditeur n’est pas suffisant. L’éditeur peut supporter un dialecte plus riche que le moteur de rendu de production.

Pour Pandoc, testez les formats d’entrée explicites :

pandoc --from=commonmark article.md -o commonmark.html
pandoc --from=gfm article.md -o gfm.html
pandoc --from=markdown article.md -o pandoc.html

Les avertissements et la ponctuation de source visible révèlent quelles fonctionnalités sont spécifiques au dialecte.

Pour Hugo, construisez le site de production :

hugo --gc --minify

Inspectez ensuite le HTML généré plutôt que de vous reposer uniquement sur un aperçu d’éditeur.

Pour les dépôts, affichez le fichier commit sur la plateforme d’hébergement réelle. Les extensions Markdown locales dans VS Code peuvent ne pas correspondre à GitHub ou GitLab.

Dépanner les incohérences de rendu courantes

Lorsqu’un fichier qui fonctionnait sur une plateforme casse sur une autre, l’échec tombe généralement dans l’un des quelques motifs répétables. Le tableau ci-dessous liste le symptôme tel que vous le verriez réellement, la cause la plus probable et une commande ou vérification concrète pour confirmer et corriger.

C’est le premier passage le plus rapide avant de supposer un « bug » Markdown — la plupart de ces incohérences sont une extension manquante ou une fonctionnalité de plateforme, pas une syntaxe cassée. Pour les problèmes spécifiques aux clôtures de code tels que la coloration syntaxique manquante ou les identifiants de langue non supportés, voir le guide dédié sur les blocs de code Markdown.

Linter le sous-ensemble portable

Un linter Markdown ne peut pas garantir la compatibilité du moteur de rendu, mais il peut supprimer l’ambiguïté évitable.

Les règles utiles incluent :

• Utiliser des styles de titre cohérents
• Ajouter des lignes vides autour des listes et blocs de code
• Utiliser du code clôturé plutôt que indenté
• Spécifier les langues de clôture de code
• Éviter les niveaux de titre sautés
• Utiliser des marqueurs de liste cohérents
• Éviter l’emphase ambiguë autour de la ponctuation
• Garder les fins de ligne cohérentes
• Valider les liens et images

Pour la publication multi-cible, ajoutez un test de build pour chaque moteur de rendu important plutôt que de vous reposer uniquement sur le linting syntaxique.

Convertir entre dialectes avec Pandoc

Pandoc peut normaliser les documents d’un dialecte à un autre :

pandoc \
  --from=markdown \
  --to=gfm \
  article.md \
  -o article-gfm.md

Ou convertir GFM en Pandoc Markdown :

pandoc \
  --from=gfm \
  --to=markdown \
  README.md \
  -o document.md

C’est utile, mais la conversion ne garantit pas de préserver chaque fonctionnalité.

Les pertes potentielles incluent :

• Références spécifiques à la plateforme
• Style des encadrés
• Tableaux complexes
• Objets d’application intégrés
• Attributs personnalisés
• Comportement HTML brut
• Syntaxe de plugin
• Rendu de diagramme
• Espaces blancs et mise en forme exacts

Pandoc préserve la structure du document mieux que le formatage de source original. Traitez la conversion comme une étape de build, pas comme un formateur de texte réversible.

Stratégie recommandée pour les sites Hugo

Pour un blog technique Hugo, la politique la plus pratique est :

1. Utiliser CommonMark pour le prose et la structure de base.
2. Activer un petit ensemble documenté d’extensions Goldmark.
3. Utiliser des tableaux et listes de tâches de style GFM là où ils améliorent la lisibilité.
4. Implémenter Mermaid à travers un hook de rendu ou shortcode cohérent.
5. Gérer les mathématiques à travers un pipeline KaTeX ou MathJax documenté.
6. Utiliser le front matter Hugo uniquement au début des fichiers de contenu.
7. Privilégier les hooks de rendu et shortcodes plutôt que le HTML brut.
8. Garder les liens source comme des liens Markdown standards là où possible.
9. Tester les documents migrés ou provenant de sources externes à travers Hugo.
10. Documenter toute syntaxe qui ne se rendra pas correctement sur GitHub.

Cette approche accepte que le contenu Hugo n’est pas universellement portable tout en gardant la limite de portabilité visible.

La pire approche est le mélange de dialectes accidentel : alertes GitHub, intégrations Obsidian, attributs Pandoc et shortcodes Hugo placés dans le même document sans pipeline de build défini.

Tableau de décision

Conclusion

CommonMark, GitHub Flavored Markdown et Pandoc Markdown ne sont pas des versions concurrentes du même produit. Ils résolvent des problèmes différents.

CommonMark fournit une fondation d’analyse fiable. GFM ajoute des fonctionnalités pratiques pour la collaboration logicielle, tandis que Pandoc Markdown transforme Markdown en un langage source riche pour la publication et la conversion.

La règle la plus sûre est simple : écrire le plus petit dialecte qui satisfait la destination réelle. Utiliser CommonMark lorsque le contenu doit voyager, GFM lorsque la collaboration de style GitHub est la cible, et Pandoc Markdown lorsque la structure du document et les formats de sortie sont plus importants que le rendu universel.

La portabilité Markdown n’est pas atteinte en évitant chaque extension. Elle est atteinte en sachant quelles extensions font partie du contrat source et en les testant dans chaque moteur de rendu qui compte.

Références

• Spécification CommonMark
• Spécification GitHub Flavored Markdown
• Pandoc Markdown
• Documentation Goldmark
• Configuration Goldmark Hugo
• Écrire des expressions mathématiques sur GitHub