SNT/sequences/markdown/MARKDOWN.md

# Guide d'utilisation Markdown

## Introduction

Markdown est un _langage de balisage_ simple créé en 2004 par John Gruber avec l'aide d'Aaron Swartz. 

En informatique, les langages de balisage représentent une classe de langages spécialisés dans l'enrichissement d'information textuelle. L'inclusion de balises permet de transférer à la fois le contenu et des indications sur la mise en forme (mise en italique, gras...).

Le HTML est un autre langage de balisage. Le Markdown est un langage plus simple à appréhender; son apprentissage facilitera celui de l'HTML.

![Logo Markdown](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/250px-Markdown-mark.svg.png)

Il a été créé dans le but 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.

## Usages

Le langage de balisage léger Markdown est utilisé dans de nombreuses applications, que ce soit dans des logiciels/éditeurs de code, des logiciels d'écriture, des plateformes de code, ou encore dans des chaînes d'édition avec l'addition d'autres logiciels. Les domaines concernés peuvent être le développement informatique, la rédaction de documentation technique ou encore la publication académique.

Certains sites comme __discord__ permettent la gestion et l'affichage de texte au format Markdown.

La plupart des cours de NSI sont au format markdown, stocké sous la forme de fichier portant l'extension .md ou .ipynb.

Pour ouvrir, modifier ou visualiser les fichiers, il faut utiliser :

- markdown (`.md`), il faut utiliser le logiciel [Typora](https://typora.io/) ou le logiciel en ligne [stackedit](https://stackedit.io/app#),
- notebook (`.ipynb`), il faut utiliser le logiciel en ligne [notebook.florianmathieu.prof](https://notebook.florianmathieu.prof/)


## Formatage

L'emphase est l'exagération d'un mot ou d'une phrase en utilisant un style ou une fonte différente de celle du reste du texte, pour mettre l'accent dessus.

En markdown, l'emphase se manifeste par les caractères _ utilisés en paire.

### Italique

Pour mettre une partie de texte en italique, il faut l'encadrer par un _.

<u>Exemple</u> : Cette _partie du texte_ est en italique.

Est obtenu par la syntaxe :
```markdown
Cette _partie du texte_ est en italique
```

### Gras

Pour mettre une partie de texte en gras, il faut l'encadrer par un double __.

<u>Exemple</u> : Cette __partie du texte__ est en gras.

Est obtenu par la syntaxe :
```markdown
Cette __partie du texte__ est en gras`
```

#### Remarque

Il est possible de cumuler le formatage de texte.

<u>Exemple</u> : Cette ___partie du texte___ est en italique et en gras.

Est obtenu par la syntaxe constituée d'une paire de triples _
```markdown
Cette ___partie du texte___ est en italique et en gras
```


### Paragraphe et saut de ligne


Pour faire un nouveau paragraphe, sauter deux lignes, c'est à dire laisser une ligne vide entre les deux paragraphes. Sauter une seule ligne dans le texte d'origine n'aura aucun effet à l'affichage (l'affichage sera en continu).

<u>Exemple</u> :

Premier Paragraphe
Deuxième Paragraphe

Est obtenu par la syntaxe suivante :
```markdown
Premier Pragraphe
Deuxième Paragraphe
```

<u>Exemple</u> :

Premier Paragraphe

Deuxième Paragraphe

Est obtenu par la syntaxe suivante :
```markdown
Premier Pragraphe

Deuxième Paragraphe
```

### Citation

Il est possible de faire des citations, c'est-à-dire formater le texte dans un style particulier différent du reste du texte, en utilisant le symbole > en début de phrase. 
Le texte est mis avec espace et une barre verticale afin de symboliser la citation.

<u>Exemple</u> :

> Moi, Monsieur, si j'avais un tel nez, il faudrait sur le champ que je l'amputasse !, Edmond Rostand / Cyrano de Bergerac

Est obtenu par la syntaxe suivante :
```markdown
> Moi, Monsieur, si j'avais un tel nez, il faudrait sur le champ que je l'amputasse !, Edmond Rostand / Cyrano de Bergerac
```

#### Citation sur plusieurs lignes

Il est possible de faire une citation sur plusieurs lignes. Dans ce cas, il faut utiliser le symbole > à chaque début de lignes constituant la citation.

<u>Exemple</u> :

> Ah ! non ! c'est un peu court, jeune homme !
>
> On pouvait dire… Oh ! Dieu ! … bien des choses en somme…
>
> En variant le ton, – par exemple, tenez :
>
> Agressif : « Moi, monsieur, si j'avais un tel nez,
>
> Il faudrait sur-le-champ que je me l'amputasse ! »
>
> Amical : « Mais il doit tremper dans votre tasse
>
> Pour boire, faites-vous fabriquer un hanap ! »
>
> Descriptif : « C'est un roc ! … c'est un pic ! … c'est un cap !
>
> Que dis-je, c'est un cap ? … C'est une péninsule ! »
>
> Curieux : « De quoi sert cette oblongue capsule ?
>
> D'écritoire, monsieur, ou de boîte à ciseaux ? »
>
> Gracieux : « Aimez-vous à ce point les oiseaux
>
> Que paternellement vous vous préoccupâtes
>
> De tendre ce perchoir à leurs petites pattes ? »
>
> Truculent : « Ça, monsieur, lorsque vous pétunez,
>
> La vapeur du tabac vous sort-elle du nez
>
> Sans qu'un voisin ne crie au feu de cheminée ? »
>
> Prévenant : « Gardez-vous, votre tête entraînée
>
> Par ce poids, de tomber en avant sur le sol ! »
>
> Tendre : « Faites-lui faire un petit parasol
>
> De peur que sa couleur au soleil ne se fane ! »
>
> Pédant : « L'animal seul, monsieur, qu'Aristophane
>
> Appelle Hippocampéléphantocamélos
>
> Dut avoir sous le front tant de chair sur tant d'os ! »
>
> Cavalier : « Quoi, l'ami, ce croc est à la mode ?
>
> Pour pendre son chapeau, c'est vraiment très commode ! »
>
> Emphatique : « Aucun vent ne peut, nez magistral,
>
> T'enrhumer tout entier, excepté le mistral ! »
>
> Dramatique : « C'est la Mer Rouge quand il saigne ! »
>
> Admiratif : « Pour un parfumeur, quelle enseigne ! »
>
> Lyrique : « Est-ce une conque, êtes-vous un triton ? »
>
> Naïf : « Ce monument, quand le visite-t-on ? »
>
> Respectueux : « Souffrez, monsieur, qu'on vous salue,
>
> C'est là ce qui s'appelle avoir pignon sur rue ! »
>
> Campagnard : « Hé, ardé ! C'est-y un nez ? Nanain !
>
> C'est queuqu'navet géant ou ben queuqu'melon nain ! »
>
> Militaire : « Pointez contre cavalerie ! »
>
> Pratique : « Voulez-vous le mettre en loterie ?
>
> Assurément, monsieur, ce sera le gros lot ! »
>
> Enfin parodiant Pyrame en un sanglot :
>
> « Le voilà donc ce nez qui des traits de son maître
>
> A détruit l'harmonie ! Il en rougit, le traître ! »
>
> – Voilà ce qu'à peu près, mon cher, vous m'auriez dit
>
> Si vous aviez un peu de lettres et d'esprit
>
> Mais d'esprit, ô le plus lamentable des êtres,
>
> Vous n'en eûtes jamais un atome, et de lettres
>
> Vous n'avez que les trois qui forment le mot : sot !
>
> Eussiez-vous eu, d'ailleurs, l'invention qu'il faut
>
> Pour pouvoir là, devant ces nobles galeries,
>
> me servir toutes ces folles plaisanteries,
>
> Que vous n'en eussiez pas articulé le quart
>
> De la moitié du commencement d'une, car
>
> Je me les sers moi-même, avec assez de verve,
>
> Mais je ne permets pas qu'un autre me les serve.

## Listes

Sauter une ligne avant le début de la liste.

### Liste non ordonnée

Pour créer une liste non ordonnée, il faut utiliser le symbole - pour chaque élément.

<u>Exemple</u> :
Listes des fruits :

- Pommes
- Poires
- Raisin

Est obtenu par la syntaxe suivante :

```markdown
Listes des fruits :

- Pommes
- Poires
- Raisin
```

___N.B : Une ligne vide doit précéder la liste et un espace est nécessaire entre le symbole - et l'élément de la liste.___

#### Remarque

Il est possible d'imbriquer des listes. Pour cela, un espace est nécessaire entre l'élément parent et la liste imbriquée.

<u>Exemple</u> :
Listes des fruits :

- Pommes
 - Golden
 - Gala
 - Pink Lady
 - ...
- Poires
- Raisin
    - Corinthe noir
    - Muscat d'Alexandrie
 
Est obtenu par la syntaxe suivante :

```markdown
Listes des fruits :

- Pommes
 - Golden
 - Gala
 - Pink Lady
 - ...
- Poires
- Raisin
 - Corinthe noir
 - Muscat d'Alexandrie
```

### Liste ordonnée

Pour créer une liste ordonnée, il faut énumérer chaque élément précédé de son rang, d'un point et d'un espace.

<u>Exemple</u> :
Liste ordonnée :

1. premier élément
2. deuxième élément
3. troisième élément

Est obtenu par la syntaxe suivante :

```markdown
Liste ordonnée :

1. premier élément
2. deuxième élément
3. troisième élément
```

#### Remarque 1

La valeur du rang ne doit pas nécessairement être indiqué. C'est le fait que chaque élément se suive qui constitue la liste ordonnée.

<u>Exemple</u> :
Liste ordonnée :

1. premier élément
1. deuxième élément
1. troisième élément

Est obtenu par la syntaxe suivante :

```markdown
Liste ordonnée :

1. premier élément
1. deuxième élément
1. troisième élément
```

#### Remarque 2

Comme pour les listes non ordonnées, il est possible d'imbriquer des listes ordonnées. Pour cela, un espace est nécessaire entre l'élément parent et la liste imbriquée.

<u>Exemple</u> :
Liste ordonnée imbriquée:

1. premier élément
 1. premier sous élément
 2. deuxième sous élément
2. deuxième élément
3. troisième élément
 1. premier sous élément

Est obtenu par la syntaxe suivante :

```markdown
Liste ordonnée imbriquée:

1. premier élément
 1. premier sous élément
 2. deuxième sous élément
2. deuxième élément
3. troisième élément
 1. premier sous élément
```

### Liste de cases à cocher

Pour créer une liste de cases à cocher, il faut énumérer chaque élément précédé par `[ ]` pour une case non cochée et `[x]` pour une case cochée.

<u>Exemple</u> :
Le langage Markdown a été créé par :

- [x] John Gruber
- [ ] Guido van Rossum
- [x] Aaron Swartz
- [ ] Bill Gates

Est obtenu par la syntaxe suivante :
```markdown
Le langage Markdown a été créé par :

- [x] John Gruber
- [ ] Guido van Rossum
- [x] Aaron Swartz
- [ ] Bill Gates
```

__N.B : Le texte entre crochets doit comporter un _seul et un seul caractère_. Soit un espace pour une case non cochée, soit un x pour une case cochée.__

## Titres

Les titres sont créés avec un certain nombre de #(croisillons) avant le titre, qui correspondent au niveau de titre souhaité (de 1 à 6).

<u>Exemple :</u>

# un titre de premier niveau
#### un titre de quatrième niveau

Est obtenu par la syntaxe suivante :
```
# un titre de premier niveau
#### un titre de quatrième niveau
```

## Tableaux

Un tableau en Markdown est constitué de 3 éléments :

1. une ligne d'en-tête
1. une ligne de séparation
1. un ensemble de lignes de corps du tableau

<u>Exemple</u> :

| Titre 1       |     Titre 2     |        Titre 3 |
| :-- | :--: | --: |
| Colonne       |     Colonne     |        Colonne |
| Alignée à     |   Alignée au    |      Alignée à |
| Gauche        |     Centre      |         Droite |


Est obtenu par la syntaxe suivante :
```
| Titre 1       |     Titre 2     |        Titre 3 |
| :-- | :--: | --: |
| Colonne       |     Colonne     |        Colonne |
| Alignée à     |   Alignée au    |      Alignée à |
| Gauche        |     Centre      |         Droite |
```

### En-tête

L'en-tête contient chaque titre de colonnes, séparés par un symbole |. Le titre sera automatiquement mis en gras.

### Séparation

La ligne de séparation permet de délimiter l'en-tête du corps du tableau et de définir l'alignement du texte du contenu de la colonne.

- `:--`: indique que le contenu est aligné à gauche de la colonne,
- `:--:`: indique que le contenu est centré,
- `--:`: indique que le contenu est aligné à droite de la colonne.

### Corps

Chaque ligne du corps du tableau contient le contenu de chaque colonne séparé par un symbole |. La couleur du fond de chaque ligne du tableau est alternée automatiquement.

## Liens

Pour créer des liens de type url cliquable, il faut utiliser la syntaxe `[texte du lien](url_du_lien)`.

<u>Exemple</u> : [Site du lycée Charlotte Perriand](https://charlotteperriand.etab.ac-lille.fr)

Est obtenu par la syntaxe :
```
[Site du lycée Charlotte Perriand](https://charlotteperriand.etab.ac-lille.fr)
```
__N.B : il n'y a pas d'espace entre le crochet fermant et la parenthèse ouvrante. Il faut écrire ..lien](url.. et non ..lien] (url.. )__

## Images

Pour afficher une image, il faut utiliser la syntaxe `![Texte alternatif](url_de_l'image)`

<u>Exemple</u> : ![Logo Markdown](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/250px-Markdown-mark.svg.png)

Est obtenu par la syntaxe :
```
![Logo Markdown](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/250px-Markdown-mark.svg.png)
```
__N.B : il n'y a pas d'espace entre le crochet fermant et la parenthèse ouvrante. Il faut écrire ..lien](url.. et non ..lien] (url.. )__

## Code

En Markdown, il est possible d'afficher du code de deux manières : en ligne (au milieu d'une phrase) ou en bloc (sur plusieurs lignes).

### Code en ligne (inline)

Pour afficher du code en ligne, il faut l'encadrer avec des accents graves `` ` `` (touche AltGr + 7 sur un clavier AZERTY).

<u>Exemple</u> : La fonction `print()` permet d'afficher du texte en Python.

Est obtenu par la syntaxe :
```markdown
La fonction `print()` permet d'afficher du texte en Python.
```

### Bloc de code

Pour afficher un bloc de code sur plusieurs lignes, il faut l'encadrer avec trois accents graves ``` ``` ```.

<u>Exemple</u> :

```
def bonjour():
    print("Hello World!")
```

Est obtenu par la syntaxe :
````markdown
```
def bonjour():
    print("Hello World!")
```
````

### Bloc de code avec coloration syntaxique

Il est possible d'ajouter le nom du langage juste après les trois premiers accents graves pour activer la coloration syntaxique.

<u>Exemple</u> :

```python
def bonjour():
    print("Hello World!")
```

Est obtenu par la syntaxe :
````markdown
```python
def bonjour():
    print("Hello World!")
```
````

Langages courants : `python`, `javascript`, `html`, `css`, `sql`, `bash`, `json`, etc.

## Lignes horizontales

Pour créer une ligne de séparation horizontale, il faut utiliser trois tirets `---`, trois astérisques `***` ou trois underscores `___` sur une ligne seule.

<u>Exemple</u> :

Texte avant la ligne

---

Texte après la ligne

Est obtenu par la syntaxe :
```markdown
Texte avant la ligne

---

Texte après la ligne
```

__N.B : Il faut laisser une ligne vide avant et après les tirets pour éviter que la ligne précédente soit interprétée comme un titre.__