Cours MD pour SOL

Quickstart guide
Exemple de code markdown
# Un titre
## Un sous titre

Ceci est un texte de paragraphe. Donc juste du texte, mais qui est mis à la ligne
automatiquement. On notera qu'il est possible de mettre du **gras** ou de l'*italique*,
ainsi que de ~~barrer~~.

Ensuite on a des listes :

* Chaque item
* Commence par une marque
* Avec sous-liste
* Suite

## Un autre sous titre

1. et une liste
1. numérotée

***Fin de l'exemple***

Exemple de rendu

Un titre
Un sous titre
Ceci est un texte de paragraphe. Donc juste du texte, peut-être un peu long, mais qui est mis à la ligne
automatique. On notera qu’il est possible de mettre du gras ou de l’italique, ainsi que de barrer.
Ensuite on a des listes :
• Chaque item
• Commence par une marque
– Avec sous-liste
– Suite

Un autre sous titre

1. et une liste
2. numérotée
Fin de l’exemple

1
Les concepts de base
Markdown est un langage de description de documents. C’est à dire que l’on décrit le document que l’on désire
obtenir en tapant le texte que l’on veut afficher et des commandes indiquant sa mise en forme et d’autres indiquant
les éléments additionnels au texte (liens, images, tableaux, etc.). Il existe d’autres langages de description de
documents :
• HTML (HyperText Markup Language) est le langage de description des pages web. Il est souvent combiné à
un autre langage intitulé CSS (Cascading Style Sheet) qui lui décrit plutôt la façon d’afficher les éléments.
• LaTeX est un langage extrêmement puissant qui permet de générer des documents. Il est en particulier
très adapté à l’écriture de formules mathématiques, mais aussi à la gestion de références bibliographiques,
d’index, de mise en page complexe, etc. Cela en fait un outil très utilisé par les scientifiques.
Markdown a été créé dans l’objectif d’être très simple et rapide à maîtriser. Son nom est d’ailleurs une référence
moqueuse au M de HTML (Markup -> Markdown) dont il s’inspire en le simplifiant. À l’origine il a été utilisé
pour générer des pages web de description de projets informatiques, mais sa simplicité l’a fait adopter bien plus
largement. Il ne permet pas de tout faire, mais de faire vite, simple et propre. C’est en particulier le langage
qui a été retenu dans les notebooks jupyter que vous utilisez dans les modules ISN et OMNI. C’est aussi le
langage utilisé dans Discord pour mettre en forme les messages. Le présent document a été écrit en Mardown.
On appelle code source le texte qui décrit le document. Sa mise en forme propre peut-être soit générée à la
volée par votre outil d’édition, soit produite à postériori (HTML, PDF, ou autre).
Un logiciel de rendu très complet est pandoc. Puisque le code est du texte brut, on peut l’éditer avec n’importe
quel éditeur de texte. Plusieurs éditeurs ont un mode dédié à Markdown, avec une coloration syntaxique
qui rend le code plus facile à lire, et une pré-visualisation dynamique du rendu (Un liste d’outils conseillés est
disponible sur la page moodle du cours).

Paragraphes
Le code comporte principalement du texte. Sans commande, particulière, il est aligné à gauche, sans justification.
C’est un paragraphe.
Pour changer de paragraphe, il suffit de sauter une ligne (laisser une ligne vide entre les deux paragraphes
successifs).
Paragraphe.

Paragraphe suivant.
Si on veut interrompre une ligne et la continuer en dessous sans changer de paragraphe, il faut terminer la ligne
par au moins deux espaces consécutifs. Par exemple,
Ceci est un saut `
à la ligne`
produit :
Ceci est un saut
à la ligne
Il n’y a pas de moyen simple d’aligner à droite, de centrer ou de justifier le texte. Pour faire ça, voir la section
Plus loin avec HTML et CSS.

Titres
Le symbole # en début de ligne, suivi d’une espace, indique un titre de premier niveau (les plus gros).
Le symbole ## indique un titre de deuxième niveau. Le symbole ### . . . ainsi de suite. Il y a six niveaux de
titres.
Les titres produisent des liens hypertextes de manière automatique. Ainsi, on peut faire un lien vers une section
## La section importante en utilisant l’URL #la-section-importante : les lettres sont mises en minuscules

2
et les espaces remplacés par des tirets. [section actuelle](#pour-faire-des-titres) donne donc un lien
vers le titre de la section actuelle. Malheureusement, c’est fait par des américains, et ça ne fonctionne pas avec
les accents et les caractères spéciaux. Formulez vos titres habilement ou n’y faites pas référence.

Formatage du texte
Pour appliquer un formatage sur un texte, il faut l’entourer avec des balises. Ainsi, si je veux mettre en gras
une partie du texte, je dois insérer la balise “mettre en gras” (**) juste avant le texte correspondant (et sans
espace avant sinon) et la même balise juste à la fin (toujours sans espace) : **mettre en gras**.

Gras et italique
Il existe plusieurs variantes du langage Markdown, mais le caractère classiquement utilisé pour le gras et l’italique
est l’étoile *. Le nombre de caractères utilisés défini la mise en forme appliquée :
• un caractère balise => *en italique* => en italique
• deux caractères => gras‘=> gras
• trois caractères => ***gras et italique*** => gras et italique
• On peut le faire au milieu d’un mot (m*ili*eu)
Note : Il faut que les balises soient collées au texte à formater. Si le positionnement des balises est mauvais,
cela donne :
** oups ** => ** oups **
** oups** => ** oups**
**oups ** => oups
**ouf** => ouf
Il est aussi possible d’encadrer un texte via deux tildes ~~ pour le barrer : ~~barré~~ => barré

Texte préformaté et code

La balise ‘ permet d’insérer du code (ou un texte pré-formaté) au sein d’un paragraphe. Exemple :
`nom_de_variable` => nom_de_variable.
Si on veut écrire un paragraphe de code et utiliser de la coloration syntaxique, on utilise la balise “‘ suivi,
éventuellement, du nom du langage utilisé :
```python
def ma_fonction_jolie():
return "Oh mais que c'est beau !"
```
produira
def ma_fonction_jolie():
return "Oh mais que c'est beau !"

Listes
Les listes fonctionnent aussi avec des symboles en début de ligne. Il y a trois types de listes, trois façons de
fonctionner.

Listes simples
Il suffit de commencer la ligne avec un * (ou - ou un +). Des lignes consécutives qui commencent par le même
symbole forment la même liste, dès qu’on change de symbole, il y aura un espacement qui montre qu’on commence
une autre liste. On peut faire des sous-listes, en indentant les lignes de la liste imbriquée.
Par exemple la liste :
• un premier niveau

3
 – un deuxième niveau
∗ un troisième niveau
– retour au deuxième
• retour au premier
S’écrit :
- un premier niveau
* un deuxième niveau
* un troisième niveau
* retour au deuxième
- retour au premier

Listes ordonnées
Pour faire une liste ordonnée, il suffit de commencer la ligne par un nombre, quelconque, suivit d’un point. Par
exemple 1.
La liste :
1. Une liste ordonnée
2. Pas besoin de numéroter les lignes soit même, c’est l’interpréteur qui le fait.
1. Et puis des listes imbriquées ça marche bien aussi
2. Et si je veux mettre dans ma liste
• une liste simple imbriquée
• c’est possible
S’écrit :
1. Une liste ordonnée
1. Pas besoin de numéroter les lignes soit même, c'est l'interpréteur qui le fait.
1. Et puis des listes imbriquées ça marche bien aussi
1. Et si je veux mettre dans ma liste
* une liste simple imbriquée
* c'est possible

Listes cochables (todo-list)

Il est possible de faire une liste à cocher en commençant la liste avec - [ ] ou - [X]
□ Choix non coché - [ ]
⊠ Choix coché - [X]

Formules en Latex
La balise $ permet d’insérer une formule en Latex au sein d’un texteP
:
42
$\sum_{x = 0}ˆ{42}\cos\left(\frac{2\pi.x}{42}\right)$ => x=0 cos 2π.x


42 .
La balise $$ permet d’insérer une formule en Latex centrée en plus grand format :
$$\sum_{x = 0}ˆ{42}\cos\left(\frac{2\pi.x}{42}\right)$$ =>

42  
X 2π.x
cos
x=0
42

Liens hypertexte
On peut évidemment insérer des liens [vers un site web] (http://www.google.com). Il suffit de mettre le texte du
lien entre crochets suivi de l’adresse de la page (on dit l’URL quand on est poli) entre parenthèse : [vers un
site web](http://www.google.com). Il peut y avoir des espaces entre les crochets et les parenthèses.

4
Pour aller plus loin
On peut faire plus évidemment que du simple texte.

Citations
la balise > permet de formater du texte pour bien l’isoler. On peut faire des citations dans les citations (comme
dans une conversation par mail par exemple), une bonne pratique est de mettre une ligne vide avant et après
chaque changement de niveau de citation.
> Une citation célèbre
> doit être bien mise en valeur
>
> Comme dans le texte, si on veut aller changer de paragraphe
>
> > Et si on cite quelqu'un qui cite quelqu'un
> >
> > > C'est presque inception
Une citation célèbre doit être bien mise en valeur
Comme dans le texte, si on veut aller changer de paragraphe
Et si on cite quelqu’un qui cite quelqu’un
C’est presque inception

Tableaux
Pour créer des tableaux, il suffit de faire les colonnes avec | et les lignes avec - :
| Ceci | est un || tableau |
| -----| -------| --------|--|
| avec une| ligne d'entête|||
| avec | plusieurs lignes| et des colonnes| de tailles différentes |

Ceci est un tableau

avec une ligne d’en-tête
avec plusieurs lignes et des colonnes de tailles différentes

Il faut que toutes les lignes du tableau aient le même nombre de colonnes (donc le même nombre de |), quitte à
ce que les cases soient vides.
La ligne d’en-tête est en gras et centrée. Le reste est, par défaut aligné à gauche. Il est possible d’indiquer
l’alignement dans les colonnes, en utilisant :---, :---: et ---: dans la séparation d’entête :
| centrée | alignée à gauche | alignée à droite | rien de précisé |
| :---: | :--- | ----: | ---------- |
| contenu long pour voir | contenu long pour voir | contenu long pour voir | contenu long pour voir|
| le court | le court |le court |le court |

centrée alignée à gauche alignée à droite rien de précisé

contenu long pour contenu long contenu long pour contenu long pour voir
voir pour voir voir
le court le court le court le court

5
Conseil pratique : récupérer un tableau d’un tableur et le mettre au format markdown peut être long si c’est
“fait à la main”. Il existe plusieurs sites et utilitaires qui vous permettent de le faire automatiquement. Par
exemple Table to Markdown.

Images
Pour inclure une image, cela fonctionne comme pour un lien vers une page web, avec un ! qui précède. Pour
inclure une image qui est en ligne, il suffit d’indiquer son URL dans les parenthèses. Pour inclure une image qui
est sur votre ordinateur, c’est le chemin vers le fichier :
 produit

Et en cas d’erreur de chargement  produit => Pas de ballon

Attention !! Il n’y a pas de moyen en markdown de contrôler la taille des images ou l’alignement (des images
et du texte). Il faut donc s’assurer que l’image qu’on insère a la taille désirée.

Dépasser Markdown avec HTML et CSS

Pour pouvoir dépasser certaines limites de Markdown, il est possible d’insérer du code HTML et CSS. Dans un
bloc de code HTML/CSS, il n’est pas possible d’utiliser la syntaxe Markdown ou LaTeX. C’est évidemment
beaucoup puissant que Markdown, mais demande un apprentissage plus long.
Par exemple, voici deux trois choses faisables :
<p style="text-decoration: underline red;"> Du texte souligné en rouge</p> =>
Du texte souligné en rouge
<p style="text-align: center;"> Du texte centré</p> =>
Du texte centré
<div align="center">
<img src = "https://www.insa-lyon.fr/sites/all/themes/insa/logo.png" width=150>
</div> =>
La balise <div> permet de donner des instructions sur le formatage de tout ce qui suit jusqu’au </div> suivant,
ici l’alignement centré. La balise <img> permet donc d’insérer une image, en donnant des indications comme la
taille, une rotation ou autre.
<img src = "/https://www.insa-lyon.fr/sites/all/themes/insa/logo.png" width=50 style="transform:rotate(-
transform-origin: 75% 0%; float:right;"/> =>
Il faut aller voir la syntaxe html/css pour aller plus loin.
Encore une fois, cela permet de tout faire, mais c’est beaucoup plus lourd et rapidement inutile pour un rapport
scientifique si vous exportez vos courbes correctement ou si vous travaillez dans un notebook jupyter.