Markdown : Écris une fois, publie partout

Tu dois écrire de la documentation. Ou un README. Ou un article de blog. Ou un message Slack avec du formatage.

HTML est excessif. Les documents Word ne fonctionnent pas partout. Le texte brut n'a pas de formatage.

Markdown se situe au sweet spot. Syntaxe simple, lisible en texte brut, se convertit en HTML quand nécessaire.

Les bases

# Titre 1
## Titre 2
### Titre 3

**gras** et *italique*

- Point de puce
- Autre point
  - Point imbriqué

1. Liste numérotée
2. Deuxième élément

[Texte du lien](https://example.com)

![Texte alternatif image](image.jpg)

C'est la plupart de ce dont tu as besoin.

Formatage de code

Code inline avec des backticks : console.log('hello')

Blocs de code avec triple backticks :

function hello() {
  return 'world';
}

Spécifie le langage après les backticks d'ouverture pour la coloration syntaxique.

Tableaux

| Nom   | Rôle        |
|-------|-------------|
| Alice | Développeur |
| Bob   | Designer    |

Les tableaux sont pénibles à taper. La plupart des éditeurs ont des raccourcis.

Citations

> Ceci est une citation.
> Elle peut s'étendre sur plusieurs lignes.

Utilise pour les encarts, citations ou mettre en avant du texte important.

Pourquoi Markdown fonctionne

Source lisible. Même sans rendu, Markdown est facile à lire. **gras** est évidemment gras.

Portable. GitHub, Notion, Slack, Reddit, d'innombrables générateurs de sites statiques. Écris une fois, colle partout.

Compatible avec le contrôle de version. C'est du texte brut. Les diffs Git ont du sens. Les merges fonctionnent.

À l'épreuve du futur. Pas de format propriétaire. Ton contenu est accessible pour toujours.

Différences de saveurs

GitHub Flavored Markdown (GFM) ajoute des cases à cocher, tableaux et coloration syntaxique.

CommonMark est l'effort de standardisation. La plupart des plateformes le supportent.

Certaines plateformes ajoutent des extras : Obsidian a des wikilinks, Notion a des bases de données.

Pour une portabilité maximale, reste à la syntaxe de base.

Erreurs courantes

Oublier les lignes vides. Les paragraphes ont besoin de lignes vides entre eux. Sans elles, tout s'enchaîne.

Espaces après les titres. #Titre ne fonctionne pas. # Titre oui. Note l'espace.

Liens cassés. Manquer le https:// fait échouer les liens sur certaines plateformes.

Images sans texte alternatif. ![](image.jpg) fonctionne mais n'est pas accessible. Ajoute des descriptions.

Conseils d'écriture

Utilise des titres pour la structure. Les lecteurs scannent avant de lire.

Garde les paragraphes courts. Les espaces blancs aident à la lisibilité.

Prévisualise avant de publier. Différents renderers gèrent les cas limites différemment.

---

Markdown retire la friction de l'écriture. Apprends les bases une fois, utilise-les partout. La simplicité est la fonctionnalité.