# Markdown — Variantes, Dialectes et Standards

> Sources : [CommonMark.org](https://commonmark.org/), [GFM Spec](https://github.github.com/gfm/), [Wikipedia — Markdown](https://en.wikipedia.org/wiki/Markdown), [RFC 7763](https://datatracker.ietf.org/doc/html/rfc7763), [RFC 7764](https://datatracker.ietf.org/doc/html/rfc7764)

---

## Le problème des dialectes

Dès 2004, des dizaines d'implémentations de Markdown sont apparues, chacune résolvant différemment les ambiguïtés du spec original de Gruber. Cela a mené à une fragmentation : un document Markdown rendu correctement sur GitHub peut s'afficher différemment sur Stack Overflow ou dans un éditeur local.

---

## 1. Markdown Original (Gruber, 2004)

| Élément | Détail |
|---------|--------|
| **Auteur** | John Gruber (avec Aaron Swartz) |
| **Date** | 2004 |
| **Implémentation** | `Markdown.pl` — script Perl |
| **Licence** | BSD |
| **URL** | [daringfireball.net/projects/markdown](https://daringfireball.net/projects/markdown/) |

**Caractéristiques :**
- Syntaxe décrite en prose, non formalisée
- De nombreuses ambiguïtés (indentation, listes, titres…)
- `Markdown.pl` avait de nombreux bugs connus
- Accepte du HTML brut dans le texte
- Ne définit pas les tableaux, notes de bas de page, ni blocs de code clôturés

---

## 2. CommonMark

| Élément | Détail |
|---------|--------|
| **Initiateurs** | Jeff Atwood, John MacFarlane et autres (2012–2014) |
| **Spec officielle** | [spec.commonmark.org](https://spec.commonmark.org/) |
| **Dernière version** | 0.31.2 (janvier 2024) |
| **Implémentation de référence** | `cmark` (C), `cmark-gfm` (fork GitHub) |
| **Licence de la spec** | Creative Commons BY-SA |

**Objectifs :**
- Spécification **formelle et non ambiguë** de Markdown
- Définit le comportement exact pour tous les cas limites
- Fournit une suite de **652 tests de conformité**
- Deux phases de parsing : (1) structure de blocs, (2) structure inline

**Ce que CommonMark définit :**
- Tous les éléments de la syntaxe de base
- Blocs de code clôturés (extension intégrée)
- Autolinks `<url>` et `<email>`
- Comportement exact des listes serrées/lâches
- Traitement des tabulations
- Caractères insécurisés (U+0000 → U+FFFD)

**Ce que CommonMark ne définit PAS** (laissé aux extensions) :
- Tableaux
- Notes de bas de page
- Listes de tâches
- Strikethrough
- Emoji

---

## 3. GitHub Flavored Markdown (GFM)

| Élément | Détail |
|---------|--------|
| **Auteur** | GitHub, Inc. |
| **Date de spec formelle** | 2017 |
| **Version actuelle** | 0.29-gfm (2019-04-06) |
| **Spec** | [github.github.com/gfm](https://github.github.com/gfm/) |
| **Base** | CommonMark Spec (superset strict) |

**GFM = CommonMark + extensions :**

| Extension GFM | Description |
|---------------|-------------|
| **Tables** | Tableaux avec `\|` et délimitateurs `:---:` |
| **Task list items** | `- [x]` et `- [ ]` |
| **Strikethrough** | `~~texte~~` et `~texte~` |
| **Autolinks étendus** | URL `www.` et emails sans `<>` |
| **Disallowed Raw HTML** | Filtrage de tags dangereux |

**Utilisé sur :**
- GitHub.com et GitHub Enterprise
- GitHub Wikis, Issues, Pull Requests, Discussions
- GitHub Pages (via Jekyll)
- README.md

---

## 4. Markdown Extra

| Élément | Détail |
|---------|--------|
| **Auteur** | Michel Fortin |
| **Date** | 2004 (PHP Markdown Extra) |
| **URL** | [michelf.ca/projects/php-markdown/extra/](https://michelf.ca/projects/php-markdown/extra/) |
| **Implémentation** | PHP |

**Fonctionnalités ajoutées :**
- Tableaux
- Notes de bas de page `[^1]`
- IDs de titres `{#id}`
- Listes de définitions
- Blocs de code clôturés
- Abbreviations `*[HTML]: HyperText Markup Language`
- Attributs HTML inline sur les spans/blocs
- Markdown dans les blocs HTML (attribut `markdown="1"`)

---

## 5. MultiMarkdown (MMD)

| Élément | Détail |
|---------|--------|
| **Auteur** | Fletcher T. Penney |
| **URL** | [fletcherpenney.net/multimarkdown](https://fletcherpenney.net/multimarkdown/) |
| **Formats de sortie** | HTML, LaTeX, PDF, OPML, OpenDocument |

**Fonctionnalités ajoutées :**
- Métadonnées YAML en en-tête
- Tableaux multi-lignes
- Notes de bas de page
- Citations croisées
- Glossaires
- Exposant `^texte^`, indice `~texte~`
- Liens vers des figures
- Math (via MathJax/LaTeX)

---

## 6. Pandoc Markdown

| Élément | Détail |
|---------|--------|
| **Auteur** | John MacFarlane |
| **URL** | [pandoc.org](https://pandoc.org/) |
| **Formats de sortie** | 40+ formats (HTML, PDF, DOCX, EPUB, LaTeX, RST, AsciiDoc…) |

**Le "couteau suisse" de la conversion de documents.**

**Fonctionnalités :**
- Tout CommonMark + nombreuses extensions optionnelles
- Notes de bas de page, listes de définitions, tableaux
- Métadonnées YAML
- Blocs `:::{.class}` pour divs génériques
- Math LaTeX `$x^2$` et `$$\int$$`
- Citations bibliographiques (`@key`)
- Exposant/indice, texte barré, surligné
- Gridtables (tableaux complexes multi-lignes)
- Listes de tâches

---

## 7. R Markdown

| Élément | Détail |
|---------|--------|
| **Auteur** | Yihui Xie / RStudio (Posit) |
| **URL** | [rmarkdown.rstudio.com](https://rmarkdown.rstudio.com/) |
| **Base** | Pandoc Markdown |

**Spécificités :**
- Intègre des **blocs de code R exécutables** (chunks) :
  ````markdown
  ```{r nom-du-chunk, echo=TRUE}
  summary(mtcars)
  ```
  ````
- Les sorties (tableaux, graphiques) sont insérées dans le document final
- Supporte Python, SQL, Bash via `knitr`
- Formats de sortie : HTML, PDF (via LaTeX), Word, Slides (ioslides, reveal.js, Beamer)
- Extension moderne : **Quarto** (`.qmd`) — successeur multi-langage de R Markdown

---

## 8. Autres variantes notables

| Nom | Auteur/Contexte | Particularités |
|-----|-----------------|----------------|
| **Kramdown** | Thomas Leitner | Utilisé par Jekyll (GitHub Pages) ; tables, footnotes, IAL |
| **Redcarpet** | GitHub (ancien) | Remplacé par CommonMark sur GitHub |
| **Discount** | David Parsons | Implémentation C rapide |
| **Maruku** | Andrea Spadaccini | Utilisé par certaines implémentations Ruby on Rails |
| **Myst** | Executable Books Project | Markdown + directives RST, pour Jupyter Book |
| **MDX** | Hashicorp/Gatsby | Markdown + JSX (React) |

---

## 9. Standards et RFC

### RFC 7763 — Type MIME `text/markdown`

- **Date** : mars 2016
- **Auteurs** : Sean Leonard
- **Contenu** : Enregistre officiellement le type MIME `text/markdown` auprès de l'IANA
- **Paramètre** : `charset` (UTF-8 par défaut), `variant` (pour spécifier le dialecte)
- **URL** : [datatracker.ietf.org/doc/html/rfc7763](https://datatracker.ietf.org/doc/html/rfc7763)

### RFC 7764 — Guidance sur les variantes Markdown

- **Date** : mars 2016
- **Auteurs** : Sean Leonard
- **Contenu** : Registre des variantes Markdown, bonnes pratiques pour l'interopérabilité
- **URL** : [datatracker.ietf.org/doc/html/rfc7764](https://datatracker.ietf.org/doc/html/rfc7764)

---

## 10. Ligne du temps des standards

```
2004  John Gruber publie Markdown 1.0 + Markdown.pl
2004  Michel Fortin crée PHP Markdown
2007  Fletcher Penney publie MultiMarkdown
2008  Pandoc 1.0 (John MacFarlane)
2012  Réunion CommonMark (Jeff Atwood, John MacFarlane…)
2014  Renommage : "Standard Markdown" → "CommonMark"
2016  RFC 7763 & RFC 7764 (IANA, type MIME text/markdown)
2017  GitHub publie la spécification GFM formelle
2019  CommonMark 0.29, GFM 0.29-gfm
2022  Quarto 1.0 (successeur de R Markdown)
2024  CommonMark spec 0.31.2 (janvier 2024)
```