Guide de Syntaxe Markdown : Des Bases aux Techniques Avancees

Qu'est-ce que le Markdown ?

Le Markdown est un langage de balisage leger cree par John Gruber en 2004. Son principe : ecrire du texte avec une syntaxe simple et lisible, qui se convertit automatiquement en HTML. Contrairement au HTML, le Markdown est concu pour etre lisible meme sous forme brute.

Le Markdown est devenu le standard de facto pour la documentation technique. On le retrouve sur GitHub (README, issues, pull requests), dans les CMS comme Hugo ou Jekyll, dans les outils de notes (Notion, Obsidian), et dans la plupart des forums techniques (Stack Overflow, Reddit).

Syntaxe de base

Titres

Les titres utilisent le caractere #. Le nombre de # determine le niveau :

# Titre 1 (H1)
## Titre 2 (H2)
### Titre 3 (H3)

Utilisez un seul H1 par document (le titre principal). Les H2 structurent les grandes sections, les H3 les sous-sections.

Mise en forme du texte

• **gras** donne gras
• *italique* donne italique
• ~~barre~~ donne du texte barre
• `code inline` donne code inline

Listes

Listes non ordonnees avec -, * ou + :

- Element 1
- Element 2
  - Sous-element

Listes ordonnees avec des numeros :

1. Premier
2. Deuxieme
3. Troisieme

Liens et images

[texte du lien](https://example.com) — un lien
![texte alternatif](image.jpg) — une image

Syntaxe avancee

Blocs de code

Entourez le code de trois backticks. Ajoutez le nom du langage pour la coloration syntaxique :

```javascript
function bonjour(nom) {
  return `Bonjour ${nom}`;
}
```

Tableaux

Les tableaux utilisent des pipes | et des tirets - :

| Colonne 1 | Colonne 2 |
|-----------|-----------|
| Cellule 1 | Cellule 2 |

Alignez le texte avec : dans la ligne de separation : :--- (gauche), :---: (centre), ---: (droite).

Citations

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

Listes de taches

- [x] Tache terminee
- [ ] Tache en cours

GitHub Flavored Markdown (GFM)

GitHub utilise une version etendue du Markdown avec des fonctionnalites supplementaires :

• Coloration syntaxique automatique dans les blocs de code
• Listes de taches avec des cases a cocher
• Tableaux (pas dans le Markdown original)
• Mentions avec @utilisateur
• References d'issues avec #123
• Emojis avec :emoji_name:
• Notes de bas de page avec [^1]

Outils pour travailler avec le Markdown

Pour rediger et previsualiser du Markdown, plusieurs options s'offrent a vous :

Editeurs en ligne

Notre Previsualiseur Markdown vous permet de rediger du Markdown et de voir le rendu HTML en temps reel, directement dans votre navigateur.

Editeurs de bureau

• VS Code : previsualisation Markdown integree (Ctrl+Shift+V). Extensions comme "Markdown All in One" pour des fonctionnalites avancees.
• Obsidian : un outil de prise de notes base sur le Markdown avec liaison bidirectionnelle entre les notes.
• Typora : un editeur WYSIWYG qui affiche le rendu en temps reel pendant la frappe.

Bonnes pratiques Markdown

• Un saut de ligne entre chaque element. Laissez une ligne vide entre les paragraphes, les titres, les listes et les blocs de code. Cela ameliore la lisibilite du source.
• Coherence dans les marqueurs de liste. Choisissez - ou * et tenez-vous-y dans tout le document.
• Texte alternatif pour les images. Ne laissez jamais ![](image.jpg) vide. Le texte alternatif est important pour l'accessibilite et le SEO.
• Limitez l'imbrication. Au-dela de 3 niveaux d'indentation, le Markdown devient difficile a lire. Restructurez votre contenu si necessaire.
• Utilisez des references pour les liens repetitifs. Au lieu de repeter la meme URL, utilisez la syntaxe de reference : [texte][ref] puis [ref]: url en bas du document.

Testez et affinez votre Markdown avec notre Previsualiseur Markdown pour vous assurer que le rendu correspond a vos attentes.