# Référence complète Markdown

Ce dossier contient une compilation complète et sourcée de tout ce qui concerne Markdown : histoire, syntaxe, variantes, outils et bibliographie.

---

## Structure du dossier

```
markdown-reference/
├── README.md                     ← Ce fichier (index)
├── 01-overview.md                ← Histoire, philosophie, adoption
├── 02-basic-syntax.md            ← Syntaxe de base
├── 03-extended-syntax.md         ← Syntaxe étendue (GFM, Markdown Extra…)
├── 04-variants-and-standards.md  ← CommonMark, GFM, Pandoc, RFC…
├── 05-tools-ecosystem.md         ← Parsers, éditeurs, plateformes
└── 06-bibliography.md            ← Sources et bibliographie
```

---

## Contenu par fichier

### [01-overview.md](01-overview.md) — Vue d'ensemble

- Qu'est-ce que Markdown et pourquoi a-t-il été créé ?
- Histoire : Gruber & Swartz (2004) → CommonMark → GFM
- Ligne du temps (tableau 2002–2024)
- Principes de conception
- Adoption : GitHub, Reddit, Stack Overflow, Discord, Obsidian…
- Extensions de fichier `.md` / `.markdown` et type MIME `text/markdown`

### [02-basic-syntax.md](02-basic-syntax.md) — Syntaxe de base

Couvre tous les éléments définis par Gruber dans le spec original :

| Élément | Couvert |
|---------|---------|
| Titres ATX (`#`) et Setext (`===`) | ✅ |
| Paragraphes et sauts de ligne | ✅ |
| Emphase (`*`, `_`, `**`) | ✅ |
| Citations (`>`) | ✅ |
| Listes ordonnées et non-ordonnées | ✅ |
| Code inline et blocs de code indentés | ✅ |
| Règles horizontales | ✅ |
| Liens (inline, reference, shortcut) | ✅ |
| Images | ✅ |
| HTML brut | ✅ |
| Échappement backslash | ✅ |
| Entités HTML | ✅ |

### [03-extended-syntax.md](03-extended-syntax.md) — Syntaxe étendue

Fonctionnalités au-delà du spec original :

| Élément | Dialecte |
|---------|---------|
| Blocs de code clôturés (` ``` `) | CommonMark + |
| Tableaux | GFM, Markdown Extra |
| Texte barré (`~~`) | GFM |
| Listes de tâches (`- [x]`) | GFM |
| Autolinks étendus | GFM |
| Notes de bas de page (`[^1]`) | Markdown Extra, Pandoc |
| IDs de titres (`{#id}`) | Markdown Extra |
| Listes de définitions | Markdown Extra, Pandoc |
| Surlignage (`==texte==`) | Extensions non standard |
| Exposant / indice | Extensions non standard |
| Emoji shortcodes (`:smile:`) | GitHub, Slack… |
| Tableau de compatibilité | ✅ (matrice complète) |

### [04-variants-and-standards.md](04-variants-and-standards.md) — Variantes et standards

Analyse détaillée de chaque variante majeure :

- **Markdown original** (Gruber, 2004)
- **CommonMark** (spec formelle, v0.31.2, 2024)
- **GFM** — GitHub Flavored Markdown (v0.29-gfm, 2019)
- **Markdown Extra** (Michel Fortin, PHP)
- **MultiMarkdown** (Fletcher Penney, écriture académique)
- **Pandoc Markdown** (40+ formats de sortie)
- **R Markdown / Quarto** (notebooks scientifiques)
- **Autres variantes** : Kramdown, MyST, MDX…
- **RFC 7763** (type MIME `text/markdown`)
- **RFC 7764** (registre des variantes)

### [05-tools-ecosystem.md](05-tools-ecosystem.md) — Outils et écosystème

Inventaire des outils disponibles :

- **Parsers / Bibliothèques** : JavaScript, Python, Rust, Go, Ruby, PHP, C, Java
- **Éditeurs dédiés** : Typora, Obsidian, iA Writer, Bear, Joplin, MarkText…
- **Générateurs de sites statiques** : Jekyll, Hugo, Docusaurus, MkDocs…
- **Plateformes** : GitHub, GitLab, Reddit, Stack Overflow, Slack, Discord…
- **Outils de conversion** : Pandoc, mdBook, Quarto, Jupyter…
- **Linters** : markdownlint, remark-lint, vale

### [06-bibliography.md](06-bibliography.md) — Bibliographie

Toutes les sources avec URLs :
- Spécifications officielles (Gruber, CommonMark, GFM)
- RFC (7763 & 7764)
- Markdown Guide
- Articles Wikipedia
- Dépôts des implémentations de référence

---

## Accès rapide — Syntaxe de base

```markdown
# Titre H1      ## Titre H2     ### Titre H3

**gras**   *italique*   ~~barré~~   `code inline`

> Citation

- Item 1       1. Premier      - [x] Fait
- Item 2       2. Deuxième     - [ ] À faire

[Lien](https://example.com)    ![Image](image.png)

| Col 1 | Col 2 |      ```python
|-------|-------|      code_block = True
| A     | B     |      ```
```

---

## Sources principales

- [Daring Fireball — Markdown](https://daringfireball.net/projects/markdown/)
- [CommonMark Spec](https://spec.commonmark.org/)
- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
- [The Markdown Guide](https://www.markdownguide.org/)