GFM vs CommonMark vs Pandoc Markdown : comparaison de la syntaxe

Markdown ressemble à une seule langue jusqu’au moment où le même fichier s’affiche différemment sur GitHub, Hugo, Obsidian ou Pandoc. Et le problème ne réside pas dans l’instabilité de Markdown.

Il réside dans le fait que « Markdown » décrit une famille de syntaxes, de parseurs et de fonctionnalités de plateforme apparentés, plutôt qu’un format de document universel unique. CommonMark définit un cœur portable et précis, GitHub Flavored Markdown ajoute des fonctionnalités utiles pour la collaboration logicielle, et Pandoc Markdown étend la langue pour en faire un véritable format d’écriture 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 de l’ensemble plus large de la documentation technique et couvre les dialectes formels, les extensions spécifiques aux plateformes et les règles pratiques de portabilité, afin que vous puissiez choisir la bonne syntaxe pour votre environnement cible. Pour une référence rapide de la syntaxe, le tableau de bord Markdown couvre les éléments de formatage essentiels.

Markdown n’est pas une seule langue

La syntaxe originale de Markdown était délibérément petite et spécifiée de manière lâche. Cela la rendait facile à lire et à implémenter, mais différents parseurs ont commencé à interpréter les entrées ambiguës différemment.

CommonMark a été créé pour définir des règles de parsing cohérentes pour les structures fondamentales de Markdown. GitHub Flavored Markdown, généralement appelé GFM, se construit sur cette fondation avec plusieurs extensions largement utilisées.

Pandoc Markdown adopte une approche différente. Au lieu de rester une petite 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éfinitions, 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 toutes les implémentations. Chaque renderer peut activer, désactiver ou ajouter la syntaxe indépendamment.

La réponse courte

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

Utilisez GFM lors de l’écriture de fichiers README, de demandes de tirage (pull requests), de modèles de problèmes (issues) et de documentation technique destinés 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 des citations et des 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 assumé : si vous ne retenez qu’une règle pour un blog technique Hugo, considérez CommonMark plus les tableaux et listes de tâches style GFM comme valeur par défaut, et considérez tout le reste — notes de bas de page, mathématiques, alertes, attributs d’en-tête — comme une extension explicite et testée plutôt que comme un défaut supposé. Cette seule habitude prévient la plupart des échecs de portabilité décrits ci-dessous.

CommonMark : Le cœur 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 un parsing cohérent.

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

• Les paragraphes
• Les en-têtes ATX et Setext
• Les citations de blocs
• Les listes ordonnées et non ordonnées
• Les blocs de code encadrés et indentés
• L’accentuation et l’accentuation forte
• Les liens et images
• Les liens en style de référence
• Le code en ligne
• Les séparations thématiques
• Les blocs HTML bruts
• Les retours à la ligne durs et doux

Un document CommonMark peut encore se comporter différemment au niveau de la présentation. CSS, la coloration syntaxique, les ancres d’en-tête, l’assainissement du HTML et les politiques de liens sont en dehors des règles de parsing du cœur.

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

Un exemple 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
```

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

Ce type de document fonctionne sur presque tous les environnements Markdown modernes. Il utilise des en-têtes, des paragraphes, des listes, du code encadré et des liens ordinaires sans dépendre des extensions spécifiques aux dialectes.

GitHub Flavored Markdown : CommonMark pour les projets logiciels

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

La spécification formelle GFM ajoute :

• Les tableaux avec barres verticales (pipes)
• Les éléments de liste de tâches
• La suppression de texte (strikethrough)
• Les autolinks étendues
• Des restrictions autour de certains balises HTML brutes

Ces extensions sont devenues si courantes que beaucoup d’utilisateurs pensent qu’elles font partie du Markdown standard. Elles ne font pas partie du cœur CommonMark.

Tableaux GFM

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

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

Listes de tâches GFM

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

La syntaxe des listes de tâches est utile dans les problèmes (issues), les demandes de tirage (pull requests) et la documentation de projet. En dehors d’un renderer supportant cette fonctionnalité, elle peut apparaître comme une liste ordinaire contenant des crochets carrés littéraux.

Suppression de texte GFM

Utilisez le ~~ancien point d'accès~~ nouveau point d'accès.

La suppression de texte est largement prise en charge, mais c’est toujours une extension plutôt qu’une syntaxe CommonMark portable.

Autolinks GFM

GFM reconnaît plus de textes semblables à des URL et à des e-mails sans nécessiter de chevrons ou d’une syntaxe de lien explicite.

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

Dans CommonMark strict, les autolinks explicites utilisent des chevrons :

<https://example.com/docs>

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

GitHub.com prend en charge plus que le GFM formel

Une source fréquente de confusion est le présupposé que chaque fonctionnalité Markdown visible sur GitHub appartient à la spécification GFM.

Ce n’est pas le cas.

GitHub.com ajoute un traitement au niveau de la plateforme et des fonctionnalités autour du parseur GFM. Selon le contexte, GitHub peut prendre en charge :

• Les expressions mathématiques
• Les diagrammes Mermaid
• Les alertes
• Les références de problèmes (issues) et de demandes de tirage (pull requests)
• Les mentions d’utilisateurs et d’équipes
• Les références de commits
• Les raccourcis d’emoji
• Les sections HTML repliables
• Les aperçus de couleurs
• Les liens relatifs au dépôt
• Les ancres d’en-tête automatiques

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

Cette distinction est importante car un autre renderer peut affirmer à juste titre une compatibilité GFM sans implémenter le renderer mathématique de GitHub, l’intégration Mermaid, les références de problèmes ou le style des alertes.

Diagrammes Mermaid GitHub

GitHub rend un bloc de code encadré marqué mermaid comme un diagramme :

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

Un renderer 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 prend en charge 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 approximativement de $2nlhd$ octets.

$$
C = 2nlhd
$$

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

Alertes GitHub

GitHub prend en charge les citations de bloc style alerte telles que :

> [!ATTENTION]
> Modifier ce réglage efface le cache.

Sur GitHub, cela peut apparaître comme une mise en garde stylée. Sur un renderer CommonMark simple, cela apparaît généralement comme une citation de bloc ordinaire contenant [!ATTENTION].

Ce repli 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 HTML, PDF, DOCX, EPUB, LaTeX, des présentations et d’autres formats.

Son lecteur Markdown par défaut inclut un large 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 tableaux
• Les listes de définitions
• La notation mathématique
• Les identifiants et attributs d’en-tête
• Les attributs de blocs de code
• Les divisions encadrées
• Les spans encadrés
• Les exposants et indices
• La suppression de texte
• 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 de la bibliographie

Pandoc Markdown est beaucoup plus expressif que CommonMark ou le GFM formel. Cette expressivité le rend puissant pour l’édition, mais moins sûr comme 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 prise en charge 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 renderer qui ne revendique que la 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 renderer non compatible, mais elle ne deviendra pas une référence formatée sans Pandoc ou un autre processeur de citations compatible. La flexibilité du côté lecteur de Pandoc soutient également les flux de conversion dans l’autre sens — voir convertir des documents Word en Markdown pour un exemple pratique de l’utilisation du dialecte étendu de Pandoc comme format intermédiaire.

Listes de définitions 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'écriture étendu pour la conversion de documents.

Les listes de définitions sont utiles dans les manuels, les glossaires et les livres techniques. Elles se dégradent généralement mal dans les renderers qui ne les prennent pas en charge, car les lignes avec 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 une liste explicite d’identifiants et de classes. De nombreux autres renderers Markdown affichent le texte des attributs directement dans l’en-tête.

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

Divisions encadrées Pandoc

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

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

La plupart des renderers 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, et non 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 prendre en charge 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 demandes de tirage, les discussions et les wikis, GFM est la base naturelle.

Vous pouvez généralement utiliser :

• La syntaxe CommonMark
• Les tableaux
• Les listes de tâches
• La suppression de texte
• Les autolinks étendues
• 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 de 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 renderer plutôt que de traiter l’aperçu GitHub comme autoritaire.

Quelle syntaxe fonctionne dans Hugo ?

Hugo utilise Goldmark comme son renderer Markdown par défaut. Goldmark est conforme à CommonMark et fournit des extensions compatibles avec des parties importantes de GFM.

Dans une configuration Hugo typique, ce qui suit fonctionne bien :

• La structure CommonMark
• Les blocs de code encadrés
• Les tableaux avec barres verticales
• La suppression de texte
• Les listes de tâches
• Les ID d’en-tête automatiques
• La coloration syntaxique
• Les notes de bas de page lorsque l’extension est activée
• Les listes de définitions lorsque activées
• Les substitutions typographiques lorsque activées

Hugo ajoute également des fonctionnalités en dehors de Markdown via :

• Les métadonnées d’en-tête (front matter)
• Les sous-programmes (shortcodes)
• Les accroches de rendu (render hooks)
• Les ressources de page
• Les fonctions de référence interne
• Le traitement des modèles
• La configuration du site

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

Les métadonnées d’en-tête Hugo ne sont pas du contenu Markdown

Une page Hugo commence généralement par des métadonnées YAML, TOML ou JSON :

---
title: "Compatibilité Markdown"
description: "Comparer les dialectes Markdown et les renderers."
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 généralement le bloc comme une section similaire à YAML ou le traite comme des métadonnées de dépôt uniquement dans certains systèmes.

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ûr par défaut dans une configuration Hugo standard.

Un bloc tel que :

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

peut être omis à moins que le rendu du HTML brut ne soit activé ou que le contenu ne soit implémenté via un sous-programme ou une accroche de rendu.

Pour un blog technique contrôlé, l’activation du HTML brut peut être raisonnable. Cela rend tout de même la source moins portable et devrait être une décision délibérée au niveau du site.

Mermaid dans Hugo

Un bloc mermaid encadré n’est toujours qu’un bloc de code à moins que le thème Hugo, l’accroche de rendu, le sous-programme ou le flux de traitement JavaScript ne le transforme en un 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 commencer par 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’extensions est puissant, mais cela signifie que « Pandoc Markdown » n’est pas toujours une configuration fixe. Les commandes de construction et les fichiers de valeurs par défaut 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’écriture 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 alertes (Callouts)
• Les références de blocs
• Les balises (Tags)
• Les propriétés
• La surbrillance
• Les commentaires
• Les requêtes Dataview des plugins
• Les liens URI spécifiques à l’application

Un lien Wiki tel que :

[[Compatibilité Markdown]]

a un sens à l’intérieur d’un coffre Obsidian. GitHub, CommonMark et un lecteur Pandoc par défaut l’affichent généralement comme du texte encadré littéral.

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

![[tableau-de-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 comme outil de gestion des connaissances, voir Obsidian pour la gestion des connaissances personnelles.

Quelle syntaxe fonctionne dans GitLab ?

GitLab Flavored Markdown utilise CommonMark comme cœur et inclut des fonctionnalités GFM telles que les tableaux et les listes de tâches. Il ajoute ensuite un comportement spécifique à GitLab, y compris 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 dommages majeurs.

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

Matrice de support des plateformes

Cette matrice décrit le comportement par défaut courant. Les thèmes, plugins, extensions et configurations peuvent modifier les 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 en-têtes ATX utilisant #
• Les paragraphes ordinaires
• Les lignes vides entre les blocs
• Le - pour les listes non ordonnées
• Le 1. pour les listes ordonnées
• Les blocs de code encadrés utilisant des backticks
• Le code en ligne utilisant des backticks
• L’accentuation utilisant *texte*
• L’accentuation forte utilisant **texte**
• Les liens ordinaires
• Les images ordinaires
• Les citations de blocs
• Les séparations thématiques
• Les autolinks explicites avec chevrons

Un document délibérément conservateur pourrait ressembler à ceci :

# Guide de déploiement

Ce guide explique comment déployer le service.

## Exigences

- Docker
- Linux
- Un GPU pris en charge

## Configuration

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

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

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

> Sauvegardez les données existantes avant la mise à niveau.

Cette syntaxe voyage bien parce qu’elle ne dépend pas des tableaux, des notes de bas de page, des attributs, des alertes ou du traitement de plateforme.

Syntaxe qui casse souvent

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 pris en charge par les outils orientés GFM, mais non par CommonMark strict.

Un tableau peut se dégrader en un texte illisible lorsqu’il est passé à travers un parseur qui ne le reconnaît pas. Pour les documents très portables, envisagez des listes courtes ou un HTML sémantique généré lors d’une étape de construction.

Notes de bas de page

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

Les différents outils peuvent :

• Ne supporter qu’un seul 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 flux de publication est connu. Évitez de compter sur elles dans les fichiers README qui doivent s’afficher sur des systèmes arbitraires.

ID 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 renderer générer sa propre ancre lorsque la portabilité est importante.

Évitez également de codifier en dur des liens vers des ID d’en-tête auto-générés à moins que chaque cible n’utilise les mêmes règles de slugification.

Alertes et avertissements

GitHub, Obsidian, GitLab, MkDocs, Docusaurus et les thèmes Hugo peuvent tous supporter des blocs semblables à des alertes, mais ils utilisent souvent des syntaxes différentes.

Un repli portable est une citation de bloc ordinaire :

> Avertissement : Sauvegardez la base de données avant la mise à niveau.

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 standard dans le contenu destiné à la publication :

[Cache KV](cache-kv.md)

HTML brut

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

Un renderer peut :

• Supprimer le HTML
• L’échapper
• Assainir certains éléments
• Autoriser les blocs mais pas les éléments en ligne
• Refuser le parsing Markdown à l’intérieur du HTML
• Le laisser 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
• Un texte ordinaire avec des signes dollar
• Une accentuation incorrecte
• Une entrée pour un parseur mathématique différent

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

Blocs de diagrammes Mermaid et autres

Une clôture de code Mermaid est syntaxiquement sûre car les renderers non compatibles l’affichent généralement 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 élégante, pas une véritable compatibilité.

Les trois niveaux de compatibilité Markdown

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

Niveau 1 : Compatibilité de parsing

Le parseur reconnaît-il la structure ?

Les exemples incluent les en-têtes, les tableaux, les notes de bas de page et les divisions encadrées.

Niveau 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èmes
• Le traitement des sous-programmes
• La génération d’une table des matières

Niveau 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 d’en-tête
• Les images responsives
• Le placement des notes de bas de page
• Les polices de mathématiques

Deux plateformes peuvent parser 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 du « Markdown valide », posez quatre questions plus étroites :

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

Par exemple :

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

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

Choisir un dialecte par cas d’usage

Fichiers README

Utilisez GFM.

Les fichiers README bénéficient de :

• Les tableaux
• Les listes de tâches
• Le code encadré
• Les autolinks
• La suppression de texte
• Les références GitHub

Évitez une dépendance excessive aux fonctionnalités exclusives à GitHub lorsque le dépôt est mirroring vers GitLab, rendu sur un registre de paquets ou inclus dans une documentation générée.

Articles techniques Hugo

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

Les tableaux, les clôtures de code, les notes de bas de page et Mermaid peuvent être raisonnables car vous contrôlez le flux de construction. Privilégiez les sous-programmes Hugo ou les accroches de rendu au lieu 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 de la bibliographie, 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 valeurs par défaut, les filtres, la bibliographie et les modèles à côté de la source. Le fichier source seul ne décrit pas complètement la construction.

Livres et documentation de longue haleine

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

Les listes de définitions, 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 uniquement Web 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 apportent une vraie valeur.

Les liens Wiki, intégrations et alertes 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 entre des systèmes inconnus

Utilisez un sous-ensemble conservateur de CommonMark.

Évitez :

• Les liens Wiki
• Les alertes de plateforme
• Les attributs d’en-tête
• Les citations
• Le HTML brut
• Les conteneurs personnalisés
• Les intégrations d’application
• Les sous-programmes

La portabilité nécessite généralement de renoncer aux fonctionnalités pratiques.

Règles pratiques pour un Markdown portable

Commencer par la structure CommonMark

Utilisez CommonMark pour le squelette du document :

• En-têtes
• Paragraphes
• Listes
• Liens
• Images
• Citations de blocs
• 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 que « la plupart des outils supportent GFM » sans tester la cible exacte. Certains revendiquent la compatibilité GFM tout en n’activant que des extensions sélectionnées.

Isoler les extensions de plateforme

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

Par exemple, centralisez les sous-programmes Hugo, les citations Pandoc ou les intégrations Obsidian plutôt que de les disperser dans chaque paragraphe.

L’isolement facilite la conversion ultérieure.

Privilégier la dégradation élégante

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

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

Choisissez des extensions dont le repli reste compréhensible.

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

Les algorithmes d’ancre d’en-tête diffèrent entre GitHub, Hugo, Pandoc et les générateurs de documentation.

Pour les liens inter-documents, utilisez uniquement des ID explicites supportés par le renderer lorsque le flux de construction cible est contrôlé. Sinon, liez au document plutôt qu’à un fragment généré.

Garder la configuration de construction avec le contenu

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

Engagez les fichiers de configuration pertinents avec la source :

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

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

Tester Markdown contre chaque cible importante

L’aperçu visuel dans un seul éditeur ne suffit pas. L’éditeur peut supporter un dialecte plus riche que le renderer 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 source visible révèlent quelles fonctionnalités sont spécifiques au dialecte.

Pour Hugo, construisez le site de production :

hugo --gc --minify

Ensuite, inspectez le HTML généré plutôt que de vous fier uniquement à un aperçu d’éditeur.

Pour les dépôts, affichez le fichier engagé 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 suivant liste le symptôme tel que vous le verriez en réalité, la cause la plus probable et une commande ou une vérification concrète pour le confirmer et le corriger.

C’est la première passe la plus rapide avant de supposer un « bug » Markdown — la plupart de ces incohérences sont une extension manquante ou une fonctionnalité exclusive à la 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 langage non pris en charge, 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 renderer, mais il peut éliminer l’ambiguïté évitable.

Les règles utiles incluent :

• Utiliser des styles d’en-tête cohérents
• Ajouter des lignes vides autour des listes et des blocs de code
• Utiliser du code encadré plutôt que indenté
• Spécifier les langues des clôtures de code
• Éviter les niveaux d’en-tête sautés
• Utiliser des marqueurs de liste cohérents
• Éviter l’accentuation ambiguë autour de la ponctuation
• Garder les fins de ligne cohérentes
• Valider les liens et les images

Pour la publication multi-cibles, ajoutez un test de construction pour chaque renderer important plutôt que de compter uniquement sur la linterisation de syntaxe.

Convertir entre les 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 :

• Les références spécifiques à la plateforme
• Le style des alertes
• Les tableaux complexes
• Les objets d’application intégrés
• Les attributs personnalisés
• Le comportement du HTML brut
• La syntaxe des plugins
• Le rendu des diagrammes
• L’espacement exact et le formatage

Pandoc préserve la structure du document mieux que le formatage de la source originale. Traitez la conversion comme une étape de construction, 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. Utilisez CommonMark pour le discours et la structure de base.
2. Activez un petit ensemble documenté d’extensions Goldmark.
3. Utilisez les tableaux et listes de tâches style GFM là où ils améliorent la lisibilité.
4. Implémentez Mermaid via une seule accroche de rendu ou un sous-programme cohérent.
5. Gérez les mathématiques via un seul flux documenté KaTeX ou MathJax.
6. Utilisez les métadonnées d’en-tête Hugo uniquement au début des fichiers de contenu.
7. Privilégiez les accroches de rendu et les sous-programmes au HTML brut.
8. Conservez les liens source comme liens Markdown standard lorsque c’est possible.
9. Testez les documents migrés ou d’origine externe à travers Hugo.
10. Documentez 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 accidentel de dialectes : alertes GitHub, intégrations Obsidian, attributs Pandoc et sous-programmes Hugo placés dans le même document sans un flux de construction 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 différents problèmes.

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

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

La portabilité Markdown n’est pas obtenue en évitant chaque extension. Elle est obtenue en sachant quelles extensions font partie du contrat source et en les testant dans chaque renderer 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