ecrire_en_markdown.md

> 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).

![](images/icones/idea.png) 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
```

![](images/icones/idea.png) 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___

![](images/icones/warning.png) 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

![](images/icones/warning.png) 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 **&#96;&#96;** *(Alt Gr+7)* ou plus ; ou utiliser la balise ```<code></code>```.
Pour une zone de code sur un paragraphe entier, il faudra utiliser trois &#96;&#96;&#96;.

![](images/icones/warning.png) L'utilisation de certaines balises, comme celles de liens, peuvent devenir problématique et obligent à utiliser les symboles &#96;&#96;, 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

``![](images/icones/idea.png)`` donnera ![](images/icones/idea.png)

---

# Liens

``[Veremes](http://www.veremes.com)``
donnera
[Veremes](http://www.veremes.com)

![](images/icones/warning.png) 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 |
````
![](images/icones/warning.png) 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``.

![](images/icones/warning.png) 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>

![](images/icones/warning.png) 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).

---