Introduction à la syntaxe Markdown

Le Markdown a été conçu pour l'écriture web, sans les complications du langage HTML (balises, en-tête...) pour faciliter la lisibilité du texte en format brut.

La syntaxe Markdown, bien que déroutant pour qui n'est pas familier avec les langages de balisages, est relativement simple. Elle est surtout constitué par des caractères de ponctuation qui évoque la signification donnée par la syntaxe. Par exemple on utilise le symbole "\*" pour mettre les mots en \*italique\*.

## Quelques élements de la syntaxe Markdown

Voici quelques élements la syntaxe Markdown. Cette section n'est pas exhaustive et ne présente pas toutes les syntaxes alternatives. À compléter.

Pour n’importe quelle fonction qui n’est pas couverte par la syntaxe de Markdown, on peut utiliser directement une balise HTML.

### Mise en évidence d'un mot

* **Mots en italique** :
	+ \*astérisque simple accolé\* = astérisque simple accolé
	+ \_simple tirets bas\_ = simple tirets bas accolés

* **Mots en caractère gras** :
	+ \*\*double astérisque\*\* = double astérisque accolés
	+ \_\_double tirets bas\_\_ = double tirets bas accolés

### Sauts de ligne et paragraphes

* Renvoi à la ligne : 2 espaces suivis d'un retour chariot
* Nouveau paragraphe : une ligne vide entre les deux paragraphes)

### Listes

* **Liste non numérotée** : utiliser "l'astérisque" (\*) suivi d'un espace, ou un "signe plus" (+) suivi d'un espace ou un tiret (-) suivi d'un espace.
* **Liste numérotée** : les listes numérotées utilisent un nombre suivi d'un point, puis d'un espace (1. 2. 3. etc.)

### Titres et sous-titres

* Mettre le signe croisillon (#), qui est souvent confondu avec le signe "dièse", devant le titre. Cela donne :
	+ # Titre de premier niveau
	+ ## Titre de second niveau
	+ ###### Titre de niveau 6

### Hyperliens

* Pour mettre un hyperlien (URL), il faut exécuter la syntaxe "[texte](URL de type http://... "Titre")". "Titre" est le titre du lien, et est optionnel.

### Citations

* Mettre le caractère ">" devant chaque ligne de la citation.

### Texte préformatté/Code

* (Voir #Comment ne pas créer un bloc de code/texte préformatté)

## Le cas des "tirets de dialogue"

La syntaxe Markdown a surtout été une syntaxe pour le balisage de textes sur le web plutôt que pour la typographie proprement dite. Un problème que rencontre souvent l'écrivant dans l'écriture via Markdown est l'absence de balise Markdown spécifique pour faire des tirets de dialogues (des tirets cadratins ou demi-cadratins). Dans ce cas, la seule solution est d'utiliser un balise HTML spécifique pour créer ces tirets.

* Pour un tiret cadratin, utilisez la balise

```
&mdash;

```

* Pour un demi cadratin, utilisez la balise

```
&ndash;

```

## Comment ne pas créer un bloc de code/texte préformatté

Markdown étant un langage pour la programmation web front-end, il existe une syntaxe spécifique pour afficher un texte préformaté, c'est-à-dire un texte qui affiche littéralement ce qu'on écrit, sous forme de blocs de code, comme ceci :

```
Bloc de code

```

Pour créer un bloc de code sur Markdown, il suffit de :

* Faire quatre espaces vides avant chaque ligne du code.

Une erreur très courante d'un écrivant débutant en Markdown est de créer des lignes de codes par inadvertance. Donc, pour **ne pas** écrire des blocs de code en Markdown, il suffit de ne pas faire d'espace avant la ligne du texte que l'on affiche.

## Quelques liens pour approfondir Markdown

Voici quelques liens vers des tutoriels ou des éditeurs de textes en ligne pour vous apprendre à écrire en Markdown et/ou en Multimarkdown (une version avancée de Markdown).

### Liens en anglais

* Official Documentation
* Sourceforge Tutorial
* Advanced Use of Markdown
* Learning Markdown, Write Web Faster : un tutoriel qui contient des éléments du Multimarkdown et des liens vers des éditeurs Markdown
* Help Multimarkdown : un tutoriel pour apprendre Multimarkdown, le Markdown avancé
* Mathew Mitchell Tutorial

### Liens en français

* Traduction de la documentation officielle
* Tutoriel d'OpenClassrooms par Mathieu Nebra