# Apprendre le *Markdown*
C’est en pratiquant qu’on apprend le mieux. Avant d’aller plus loin dans ce tutoriel, je vous propose d’utiliser [cette page](https://spec.commonmark.org/dingus/) — qui est aussi un valideur syntaxique —, à moins que vous n’ayez déjà installé *Obsidian*. Si tel est le cas, je vous propose de créer une page “Test” et de vous amuser en testant au fur et à mesure de votre lecture.
*Markdown* existe en [[différentes saveurs de Markdown|différentes « saveurs »]] (“flavors”, en anglais), c’est-à-dire que, selon que vous l’utilisez dans *Obsidian*, dans *Wordpress* ou ailleurs, il y a de menues différences, des « extensions » qui sont disponibles ou pas. Mais ne vous faites aucun souci, *Obsidian* colle de très près à ce qui est le plus standard, y compris dans ce qu’il ajoute au « basique » et qu’on pourrait considérer comme des *extensions*. Il a tout ce qu’il faut pour bien travailler.
### Le texte « normal »
En *Markdown*, un paragraphe, c’est du texte au kilomètre. C’est « tout le texte jusqu’à la prochaine ligne vide ». Ce sont les lignes vides qui délimitent les paragraphes. On peut en mettre autant qu’on veut, les lignes vides supplémentaires sont ignorées, conformément à la bonne pratique de la typographie. C’est juste pour la lisibilité du texte source qu’on peut en rajouter. Personnellement, j’en ajoute volontiers au-dessus des titres pour repérer plus facilement les blocs logiques.
Quand on souhaite un « retour à la ligne sans commencer un nouveau paragraphe », on termine la ligne par deux espaces, comme ceci (j’ai matérialisé les espaces par des points) :
> Une première ligne, dont le texte…･･
> continue sur une deuxième…･･
> et se termine sur une troisième.
**Une petite particularité** d’*Obsidian* : quand on écrit des fiches, c’est assez souvent, qu’on veut aller à la ligne sans créer un nouveau paragraphe. Alors, dans *Obsidian*, on peut le faire — “just do it !” Mais, pour que ça fonctionne, il ne faut PAS activer cette préférence, dans le panneau “Editor” des préférences :
![[Strict line breaks preference.png]]
C’est une toute petite entorse au purisme qu’on peut parfaitement se permettre dans nos fiches. Je vous la recommande.
### Italique et gras
| Dans le texte source | En mode “lecture” |
| --------------------------------------------------- | ---------------------------------------------- |
| Italique : entre \*astériques\*. | Italique : entre *astérisques*. |
| Gras : entre \*\*deux astériques\*\*. | Gras : entre **deux astérisques**. |
| Gras-italique : entre \*\*\*trois astériques\*\*\*. | Gras-italique : entre ***trois astérisques***. |
L’élégance d’*Obsidian* et d’autres éditeurs de *Markdown*, c’est qu’on peut très bien utiliser les raccourcis clavier `⌘I` et `⌘B` pour mettre en italique ou en gras (“Bold”), comme dans tous les traitements de texte.
### Titres et sous-titres
On note les titres et sous-titres en commençant la ligne par ==1 à 6 dièses== suivis d’une espace. Le nombre de dièses indique le niveau hiérarchique.
| Dans le texte source | En mode “lecture” |
| ------------------------------- | ---------------------------------|
| \# Titre de niveau 1 | <h1>Titre de niveau 1</h1> |
| \#\# Titre de niveau 2 | <h2>Titre de niveau 2</h2> |
| \#\#\# Titre de niveau 3 | <h3>Titre de niveau 3</h3> |
### Listes
Il suffit de commencer la ligne par ==un astérisque suivi d’une espace==[^1] — pour les listes à puce — ou par ==un nombre suivi d’un point et d’une espace== — pour les listes numérotées. On peut aussi utiliser des `+` ou des `-` (tiret), à la place des astérisques, c’est une question de goût ou d’habitude. À l’arrivée, c’est la feuille de style qui définira l’aspect visuel des choses.
| Dans le texte source | En mode “lecture” |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Liste à puces :<br /><br />\* premier item de la liste ; j’en fais un long paragraphe pour démontrer la gestion des retraits ;<br />\* deuxième item de la liste ;<br />\* troisième item de la liste. | <p>Liste à puces :</p><ul><li>premier item de la liste ; j’en fais un long paragraphe pour démontrer la gestion des retraits ;</li><li>deuxième item de la liste ;</li><li>troisième item de la liste.</li></ul> |
| Liste numérotée :<br /><br />1. premier item de la liste ;<br />2. deuxième item de la liste ; si le paragraphe se prolonge, \*Markdown\* fait très bien les choses !<br />3. troisième item de la liste. | Liste numérotée :</p><ol><li>premier item de la liste ;</li><li>deuxième item de la liste ; si le paragraphe se prolonge, *Markdown* fait très bien les choses !</li><li>troisième item de la liste.</li></ol> |
Comme on peut le voir dans mon document de démonstration, on peut sans autres entremêler un niveau de liste à puce à l’intérieur d’une liste numérotée — ou le contraire.
### Liens
Pour écrire des liens, on met ==entre crochets== le texte en clair, suivi immédiatement du lien lui-même, ==entre parenthèses==. Comme ceci :
| Dans le texte source | En mode “lecture” |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| Voici \[le site](https:\//obsidian.md) de l’application \*Obsidian\*. | Voici [le site](https://obsidian.md/) de l’application *Obsidian*. |
On peut aussi utiliser une syntaxe avec des références, laquelle convient mieux aux liens qui sont longs. Mais j’en déconseille l’utilisation dans *Obsidian*, car elle rend très compliqués le copier-coller et le déplacement des liens d’une fiche à une autre.
### Images
Pour les images, la syntaxe est exactement la même que celle pour les liens, il suffit d’ajouter un ==point d’exclamation== juste avant le crochet ouvrant.
| Dans le texte source | En mode “lecture” |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| Voici le logo de \*Wikipedia\* :<br />!\[La description (optionnelle)](https://upload.wikimedia.org/wikipedia/commons/thumb/d/de/Wikipedia_Logo_1.0.png/220px-Wikipedia_Logo_1.0.png) | Voici le logo de *Wikipedia* :<br /> |
| Voici mon logo : !\[logo Dr O. Spinnler](https:\//dr-spinnler.ch/myfiles/logos/Logo-Dr.png) | Voici mon logo :  |
### Notes de bas de page
C’est une des seules « particularités » d’*Obsidian* où il s’écarte de ce qui est considéré « standard » : la syntaxe «==un circonflexe== suivi de ==crochets encadrant== le texte de la note », comme ceci :
| Dans le texte source | En mode “lecture” |
| ---------------------------------------------------------------------------------------------------- | ------------------------ |
| Du texte \^\[A quick footnote.]. | Du texte^[A quick footnote.]. |
Les notes de bas de page avaient été oubliées par John Gruber quand il a proposé le *Markdown*. Il a donc bien fallu trouver quelque chose, car c’est vraiment souvent qu’on les utilise. Dans *Obsidian*, je vous recommande sans réserve la syntaxe que je viens d’indiquer. Mais sachez qu’ailleurs, c’est plutôt la syntaxe suivante qui est considérée « standard » — elle fonctionne aussi dans *Obsidian*, bien évidemment.
Pour les notes plus longues — plus d’un paragraphe —, on procède ainsi : l’appel de note se met entre crochets, le premier caractère étant un circonflexe. L’appel de note peut être un chiffre ou un label descriptif.
Plus loin dans le texte — n’importe où, vraiment —, on reprend le label entre crochets, suivis d’un “deux-points” et l’on écrit le texte de la note. C’est plus difficile à expliquer qu’à montrer ou qu’à utiliser :
| Dans le texte source | En mode “lecture” |
| ---------------------------------------------------------------------------------------------------- | ------------------------ |
| Voici une note \[^note_démo].<br /><br /> \[^note_démo]: Le texte de la note de démonstration. | Voici une note [^note_démo]. |
[^note_démo]: Le texte de la note de démonstration.
Je trouve souvent commode d’utiliser un texte descriptif pour les notes, en particulier quand il y en a plusieurs dans le texte. Ça simplifie grandement l’édition quand on remanie son texte. Mais en mode “lecture”, les notes sont simplement numérotées dans l’ordre chronologique.
### Citations
Comme dans nos e-mails, il est assez souvent utile de faire des citations. La syntaxe est d’ailleurs la même : il s’agit de commencer les lignes — ou les paragraphes — par des `>`.
| Dans le texte source | Comment c’est rendu par l’interpréteur |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| > Le texte cité.<br />> <br />> Un deuxième paragraphe.<br />><br />>> On peut aussi indenter à un deuxième niveau.<br />>><br />>> ### Et même mettre des titres dans les citations<br />>> Étonnant, non ?<br />><br />>Ici, on revient au niveau 1 de la citation. | <blockquote><p>Le texte cité.</p><p>Un deuxième paragraphe.</p><blockquote><p>On peut aussi indenter à un deuxième niveau.</p><h3>Et même mettre des titres dans les citations</h3><p>Étonnant, non ?</p></blockquote><p>Ici, on revient au niveau 1 de la citation</p></blockquote> |
### Ligne horizontale
Dernier élément que j’utilise très régulièrement, la ligne horizontale. Elle peut être utile pour séparer visuellement des idées ou des sections de texte. Je l’utilise généreusement dans mes notes. On l’obtient en tapant ==au moins trois tirets==, seuls dans un paragraphe (= une seule ligne). Pour l’agrément visuel, j’en mets souvent plus (j’ai un raccourci clavier *ad hoc*) :
```
----------------------------------------------
```
↑ cette ligne de tirets sera généralement rendue par une ligne horizontale faisant toute la largeur de la colonne de texte. Dans certaines situations et suivant la feuille de style utilisée, elle pourrait aussi bien être rendue par un ornement ou par un saut de page. Cela pourrait être le cas dans un “e-book”, par exemple.
### Les tables
La syntaxe n’est pas très compliquée, mais vous n’avez même pas besoin de l’apprendre ! Il suffit, en effet, d’installer le plugin “Advanced Tables” que vous trouverez dans les “Community Plugins”. Faites-le sans hésiter. Une fois que vous l’avez installé, procédez de la manière suivante pour insérer et éditer une table dans votre texte.
1. Laisser une ligne vide puis tapez un “pipe” `|` (`Option–7` sur Mac) suivi d’un `↩︎` (Enter) et vous obtenez ceci :
![[Elementary table — edit mode.png]]
C’est la plus élémentaire des tables : une cellule d’en-tête, une cellule du corps de la table.
2. À partir de là, il est très facile d’éditer la table, grâce au plugin “Advanced Tables”. Si vous avez très peu de texte à mettre dans les cellules, cela suffira.
3. Si vous avez beaucoup de texte à mettre dans les cellules, je vous recommande de ne pas insister dans *Obsidian* et d’éditer la fiche avec *Typora*, qui est le meilleur des éditeurs que je connaisse pour ce faire. ⭢ [[éditer une fiche avec un éditeur externe]]
### Encore trois choses utiles
Tout ce que je viens de montrer est disponible partout où l’on trouve du *Markdown*. C’est ce qu’on va utiliser 99 % du temps et ça suffit à la prise de notes et à la confection de nos fiches. J’utilise encore volontiers, parmi les autres possibilités :
* La syntaxe particulière pour les “==todo lists==” :
`- [ ] item cliquable` qui donne
- [ ] item cliquable
* La possibilité de ==citer du code==, comme quand j’écris que l’extension d’un fichier *Markdown* est `.md`. Il suffit de mettre entre deux accents graves (“backticks” en anglais) : \`.md\`.
* La possibilité de mettre — quand même — du ==code HTML== au milieu du texte en *Markdown*. C’est ainsi que je mets ma signature (cliquable !) et la date, centrées, au bas des pages de ce site. J’ai évidemment une macro *Typinator* pour cela !
* La possiblité de mettre en évidence du texte avec des `==` comme ceci :
Ceci est du ==texte surligné==, comme avec un [STABILO BOSS](https://www.stabilo.com/fr/produits/surligner/surligneurs/stabilo-boss-original/).
Parmi les possibilités que je n’exploite pas — pas encore ? —, je citerai :
* Les références bibliographiques.
* La possibilité d’insérer des équations mathématiques, avec la même syntaxe que pour le *LaTex* — c’est quelque chose que les scientifiques apprécient.
* Les diagrammes en syntaxe [*Mermaid*](https://mermaid-js.github.io/mermaid/) :
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
<p style="text-align: center;"> </p>
<p style="text-align: center;"><a href="https://dr-spinnler.ch"><img src="https://dr-spinnler.ch/myfiles/logos/Olivier-Spinnler.png" class= "signature"/></a></p>
<p style="text-align: center; font-style: italic;">le 15 juin 2021
</p>
 
[^1]: Non, je ne me suis pas trompé : *astérisque* est bien du genre **masculin** et, en typographie, on dit **une** espace, comme on dit *une* lettre.
----------------------------------------------
[[Markdown (domaine)|Markdown]]
#markdown #écriture