> Markdown est un langage de balisage léger [dont le] but est d'offrir une syntaxe facile à lire et à écrire. Un document balisé par Markdown peut être lu en l'état sans donner l’impression d'avoir été balisé ou formaté par des instructions particulières Il est aussi très facilement converti en HTML [et peut en comporter en amont]. [(source)](https://fr.wikipedia.org/wiki/Markdown).
 Ce document a pour objectif de résumer les principales balises utilisées lors de rédactions en Markdown. Pour consulter la charte rédactionnelle, se référer à la page [Règles d'usage](documentation_regles_usage.md).
---
# Textes
## Titres
Le langage Markdown permet jusqu'à 6 niveaux de titres. Pour créer un titre, il suffit de le précéder d'un nombre de ```#``` équivalent au niveau désiré.
```
# Titre de niveau 1
## Titre de niveau 2
...
###### Titre de niveau 6
```
 Cette méthode peut être remplacée par l'ajout de ```==``` ou ```--``` (deux ou plus) en-dessous du texte à titrer, **uniquement pour les titres de niveau 1**.
```
Titre de niveau 1
===
Titre de niveau 1
-------
```
## Graisse & graphie
### Gras
Entourer l'expression désirée par deux ```**```.
**Texte en gras** = **Texte en gras**
### Italique
Entourer l'expression désiré par un ```*```.
*Texte en gras* = *Texte en italique*
### Soulignement
Entourer l'expression désiré par trois ```_```.
Exemple :
Souligner = ___Souligner___
 A noter que le soulignement est considéré comme du gras par de nombreux outils (Atom, GitHub, ReadTheDocs...) et est donc à éviter.
## Listes
Une liste à puce est créée en précédant chaque item d'un * ou d'un -.
Une sous-liste se forme en rajoutant un espace avant la puce (autant d'espaces que de niveaux désirés).
Exemple :
```
* Elément 1
- Elément 2
- Elément A
```
donnera
- Elément 1
- Elément 2
- Elément A
 A noter que GitHub n'affiche qu'un seul niveau de liste.
Pour une liste numérotée, il suffit d'indiquer les chiffres souhaités, suivis d'un point.
Exemple :
```
1. Elément 1
2. Elément 2
3. Elément A
```
donnera
1. Elément 1
2. Elément 2
3. Elément A
## Zones de code
Pour intégrer une zone de code au sein d'une ligne, il faut utiliser deux symboles **``** *(Alt Gr+7)* ou plus ; ou utiliser la balise ```<code></code>```.
Pour une zone de code sur un paragraphe entier, il faudra utiliser trois ```.
 L'utilisation de certaines balises, comme celles de liens, peuvent devenir problématique et obligent à utiliser les symboles ``, voire à intégrer des sauts de lignes entre l'ouverture et la fermeture de la zone.
A noter enfin que la méthode "classique" acceptée par Atom (espacer un paragraphe de 4 espaces ou plus) n'est pas fonctionnelle sur GitHub.
## Citations
Un paragraphe de citation est précédé du symbole ```>```.
Exemple :
```
> Citation
```
donnera
> Citation
---
# Images
```` donnera 
---
# Liens
``[Veremes](http://www.veremes.com)``
donnera
[Veremes](http://www.veremes.com)
 Read the Docs peut mal interpréter une adresse web si "http://" est absent. Il est donc déconseillé d'écrire simplement "www.site.com".
Il est aussi possible d'insérer un lien rapidement en le balisant. Ainsi, ``<http://www.lien.com>`` devient <http://www.lien.com>
---
# Tables
Deux solutions existent : l'utilisation du Markdown et du HTML.
En Markdown, une cellule est créée avec ``|``, la ligne d'en-tête est suivie d'au moins trois ``-``.
````
| Col 1 | Col 2 | Col 3 |
| ------------- |:-------------:| -----:|
| L 1 | Contenu 1A | Contenu 1B |
| L 2 | Contenu 2A | Contenu 2B |
| L 3 | Contenu 3A | Contenu 3B |
````
 Les tableaux ne font pas partie des balises originelles de Markdown, aussi ils n'apparaîtront pas sur ReadTheDocs.
En HTML, une table se créée avec les balises ``<table>``, ``<tr>`` et ``<td>``. Certains styles peuvent être inclus.
```
<table>
<tr>
<td>
Col 1
</td>
<td>
Col 2
</td>
<td>
Col 3
</td>
</tr>
<tr>
<td>
L1
</td>
<td>
Contenu 1A
</td>
<td>
Contenu 1B
</td>
</tr>
</table>
```
donnera
<table>
<tr>
<td>
Col 1
</td>
<td>
Col 2
</td>
<td>
Col 3
</td>
</tr>
<tr>
<td>
L1
</td>
<td>
Contenu 1A
</td>
<td>
Contenu 1B
</td>
</tr>
</table>
---
# Cas particuliers
## Ancres
Comme en HTML, une ancre se place après un <code>#</code> à la fin d'une adresse.
Si l'on vise une ancre dans la même page :
```
[Chapitre Textes](#textes)
```
donnera [Chapitre Textes](#textes).
Pour atteindre le chapitre ["Les composants logiciels de GTF"](http://doc-gtf.readthedocs.io/fr/latest/bienvenue.html#les-composants-logiciels-de-gtf) dans un autre document, il faudra écrire ``http://doc-gtf.readthedocs.io/fr/latest/bienvenue.html#les-composants-logiciels-de-gtf``.
 Read the Docs pose trois problèmes à anticiper :
* conversion automatique des pages .md en .html
* modification de la casse (tout en minuscule ; pas d'accents ; espaces remplacés par des traits d'union )
* les ancres ne sont effectives que sur des titres, les balises ``<a name="ancre"></a>`` ne sont pas fonctionnelles sur ReadTheDocs.
## Chemins des liens
Dans le cadre d'un chemin relatif dont la cible se situe en amont du dossier actuel, il faut rajouter autant de ``../`` par dossier à remonter.
Ainsi, atteindre le chemin "doc_interne/blob/master/" à partir de "doc_interne/blob/master/developpement", il faut écrire ``../cible.md``. Pour atteindre le dossier "/blob", il faudra écrire ``../../cible.md``.
## Références
Que ce soit pour les liens ou les images, il est possible d'utiliser les liens avec un système de référence ``[Veremes][1]`` puis, ailleurs dans le document, écrire <code>[1] : www.veremes.com</code>
 Ceci n'est pas fonctionnel sur Atom et ReadTheDocs.
## Traits de séparation
Utiliser trois traits d'union (ou plus) sur la ligne désirée : ```---```. Ils précèdent généralement les titres de niveau 1 (sauf le premier titre de la page).
---