Rédiger sur ZdS

Paragraphes

Les paragraphes s’écrivent naturellement, en sautant une ligne :

Ceci est mon premier paragraphe.

Ceci est mon second paragraphe.

Tout comme avec le Markdown standard, on change de paragraphe en sautant une ligne. Un simple retour à la ligne ne suffit donc pas et sera interprété comme un simple espace :

Ceci est mon premier paragraphe.
Ici, je reviens à la ligne, mais cette phrase sera toujours dans le premier paragraphe.

Ceci est mon second paragraphe.

Si vraiment vous tenez à revenir à la ligne sans changer de paragraphe, comme ceci
par exemple, alors il suffit de terminer la première ligne par deux espaces.

De plus, le Markdown standard autorise l’insertion de HTML, mais pour des raisons de sécurité nous avons choisi de ne pas laisser cette possibilité. Si vous écrivez du HTML, celui-ci apparaitra donc tel quel dans votre texte.

Titres

Les titres sont précédés d’un ou plusieurs croisillons suivant le niveau hiérarchique voulu. Ainsi, un titre de premier niveau s’écrit avec un seul croisillon, un titre de deuxième niveau avec deux croisillons, etc.

# Titre de niveau 1

## Titre de niveau 2

### Titre de niveau 3

#### Titre de niveau 4

Quatre niveaux hiérarchiques sont disponibles. J’attire d’ailleurs votre attention sur ce point car il est très important de donner la bonne hiérarchie à vos titres lorsque vous rédigerez vos tutoriels.

Emphases

Les emphases permettent de mettre un morceau de votre texte en valeur. Deux types d’emphases sont disponibles : l’italique et le gras.

Pour mettre du texte en italique, utilisez l’astérisque ou le souligné (underscore) :

Le mot *italique* est en italique.

ou

Le mot _italique_ est en italique.

Pour mettre du texte en gras, le principe est le même, en doublant le symbole :

Le mot **gras** est en gras.

ou

Le mot __gras__ est en gras.

Par souci de simplicité et de lisibilité, vous ne pourrez pas mettre du texte en couleur, le souligner, changer sa taille ou bien encore en changer la police.

Barrer

Barrer du texte (comme ceci) se fait en utilisant deux tildes successifs avant et après la portion de texte concernée :

Le mot ~~barré~~ est barré.

Pour information, il s’agit de la syntaxe utilisée par Pandoc.

Alignement du texte

Par défaut, le texte est bien évidemment aligné à gauche. Comme nous le verrons plus loin, certains éléments sont centrés automatiquement, comme les images seules dans leur paragraphe par exemple. Vous n’avez donc en général pas à vous soucier de l’alignement du texte : le site s’en charge pour vous.

Dans les rares cas où vous souhaiteriez centrer volontairement un texte (si l’envie vous prenait d’écrire un poème par exemple), vous pourriez néanmoins utiliser la syntaxe ci-dessous :

-> Ce texte est centré. <-

Le texte est simplement entouré de deux petites flèches (tiret et chevron) de directions inversées. Pour aligner à droite, on utilise deux flèches dirigées vers la droite :

-> Ce texte est aligné à droite. ->

Il est impossible d’imbriquer des alignements. Cela n’aurait de toute façon pas de sens (comment aligner à droite un texte centré ?).

Encore une fois, l’alignement est géré automatiquement dans la majorité des cas. N’en abusez pas, cela pourrait gêner la lecture.

Enfin, sachez qu’il est impossible de justifier du texte sur le site.

Indices et exposants

Là encore, ce sont les syntaxes de Pandoc qui sont utilisées pour mettre en indice ou en exposant une portion de texte.

On utilise l’accent circonflexe pour l’exposant. Si par exemple on veut écrire que 2¹⁰ vaut 1024, alors on écrira :

2^10^ vaut 1024.

Pour l’indice, comme dans H₂O par exemple, on utilise cette fois le tilde :

La molécule de l'eau est H~2~O.

Vous pouvez utiliser deux types de liste :

• les listes non ordonnées (comme la présente) ;
• les listes ordonnées par chiffres arabes.

C’est peut-être la syntaxe la plus intuitive du Markdown ! Il suffit de matérialiser les puces par des tirets :

- Ma très belle ;
- liste ;
- à puces.

Ou bien par des chiffres :

1. Mon premier.
2. Mon second.
3. Mon troisième.

Prenez simplement garde à bien sauter une ligne avant et après vos listes.

Pour faire une sous-liste, indentez les puces imbriquées avec quatre espaces :

- Ma très belle ;
- liste ;
    - avec une sous-liste ;
- à puces.

On obtient ainsi :

• Ma très belle ;

• liste ;

  • avec une sous-liste ;
• à puces.

Il existe deux façons d’écrire des liens : avec ou sans texte d’ancrage.

Liens et emails avec texte d’ancrage

Pour faire un lien sur un morceau de texte (qu’on appelle donc texte d’ancrage, ici le mot "lien"), on utilise la syntaxe suivante :

Pour faire un [lien](https://zestedesavoir.com "Zeste de Savoir") sur un morceau de texte

Attention à ne pas mettre d’espace entre la partie concernant le texte d’ancrage (entre crochets) et la partie concernant l’URL (entre parenthèses).

Le titre du lien (ici "Zeste de Savoir" entre guillemets) est optionnel. S’il est renseigné, il apparaît sur le lien au passage de la souris.

Les emails peuvent s’écrire de la même façon que les liens. Pensez simplement à ajouter la mention "mailto:" :

Pour nous contacter, cliquez [ici](mailto:contact@monsite.com).

Liens présentés sous forme d’URL ou d’email

Si vous ne souhaitez pas utiliser de texte d’ancrage et ainsi rendre une URL ou un email cliquable, alors vous n’avez rien à faire : URL et emails seront automatiquement cliquables.

Pour les emails, vous n’avez donc même pas besoin de vous soucier du "mailto".

Des tableaux simples

Pour faire un tableau, la façon la plus simple est encore de le dessiner, à l’aide de barres verticales et de tirets :

Nom | Age
---|---
Fred | 39
Sam | 38
Alice | 35
Mathilde | 35

L’exemple ci-dessus donnera donc :

Cette syntaxe est simple mais elle a ses limites : il est impossible de revenir à la ligne dans une cellule ou bien de fusionner des lignes ou des colonnes. Si vous avez vraiment besoin de faire cela, il vous faudra utiliser une autre syntaxe de tableau, plus lourde mais plus complète, comme nous allons le voir à présent.

Tableaux complexes

Pour des tableaux plus complexes, dans lesquels vous pourrez notamment revenir à la ligne dans une cellule et fusionner des lignes ou colonnes, il vous faut utiliser la syntaxe dite « grid-table » :

+-------+----------+------+
| Table Headings   | Here |
+-------+----------+------+
| Sub   | Headings | Too  |
+=======+==========+======+
| cell  | column spanning |
+ spans +----------+------+
| rows  | normal   | cell |
+-------+----------+------+
| multi | cells can be    |
| line  | *formatted*     |
|       | **paragraphs**  |
| cells |                 |
| too   |                 |
+-------+-----------------+

Ce qui vous donnera :

Légendes de tableaux

Quelle que soit la syntaxe utilisée, vous pouvez indiquer une légende à votre tableau en ajoutant une ligne Table: Ma légende juste en dessous du tableau.

Le mot « Table » est optionnel, pas les deux-points. Il peut y avoir un espace entre « Table » et les deux-points.

Nom | Age
---|---
Fred | 39
Sam | 38
Alice | 35
Mathilde | 35
Table: Tableau des âges

Lignes horizontales

Pour tracer une ligne horizontale, le principe est le même : dessinez-là. La syntaxe est cette fois bien plus simple puisqu’elle n’est constituée que de trois tirets (ou plus, ça ne change rien au résultat) :

------

Voici le résultat :

Une formule mathématique s’écrit à l’aide d’expressions TeX Math, en l’entourant de deux caractères dollars $$ :

$$a \cdot x^2 + b \cdot x + c = 0 \quad \Longrightarrow \quad x = \frac {-b \pm \sqrt{b^2 - 4ac}}{2a}$$

Ce qui donne :

$a \cdot x^2 + b \cdot x + c = 0 \quad \Longrightarrow \quad x = \frac {-b \pm \sqrt{b^2 - 4ac}}{2a}$

En faisant ainsi, votre formule est en mode displayed : elle est dans son propre paragrpahe et s’affiche en prenant ses aises. Ainsi les chiffres et autres symboles sont écrits en grande taille et sont facilement lisibles.

Si vous voulez écrire votre formule au sein même d’un paragraphe (comme ceci : $a \cdot x^2 + b \cdot x + c = 0$), alors n’utilisez cette fois qu’un seul caractère dollar $ avant et après votre formule. Par exemple :

Si vous voulez écrire votre formule au sein même d'un paragraphe (comme ceci : $a \cdot x^2 + b \cdot x + c = 0$),
 alors n'utilisez cette fois qu'un seul caractère dollar $ avant et après votre formule.

Comme pour les tableaux, vous pouvez mettre une légende à votre formule, en ajoutant une ligne Equation: Ma légende juste en dessous.

Si vous souhaitez écrire deux symboles $ dans une même ligne, alors il vous faut échapper au moins l’un des deux (c’est-à-dire les faire précéder d’un antislash : \$) afin que le texte ne soit pas considéré comme une formule mathématique.

Bloc de code

Il n’est pas rare d’illustrer son propos d’un petit exemple de code :

#!/usr/bin/env python3

print("Hello, World!")

Pour cela, il existe plusieurs solutions.

Première solution : entourer votre code d’au moins trois accents graves ``` (Alt Gr + 7), avant et après :

```
#!/usr/bin/env python3

print("Hello, World!")
```

Le langage utilisé sera détecté automatiquement et donc coloré en conséquence. Si tel n’est pas le cas, vous pouvez forcer le langage en l’indiquant à la suite des caractères ouvrants :

```python
#!/usr/bin/env python3

print("Hello, World!")
```

La liste des langages supportés est celle de pygment, vous la trouverez ici. Les mots-clés à insérer pour déclencher la coloration sont les « short names » disponibles sur cette page.

Seconde solution, faites précéder chaque ligne de quatre espaces ou bien d’une tabulation :

    #!/usr/bin/env python3
    
    print("Hello, World!")

Là encore, vous pouvez mettre une légende à votre bloc de code en ajoutant, juste en dessous du bloc, une ligne Code: Votre légende.

Mise en évidence de lignes de code

Mettre en évidence une portion de code permet d’appuyer votre explication. Après le nom du langage, indiquez simplement les lignes à surligner avec la mention hl_lines. Vous pouvez surligner les lignes unes à unes ou par groupes. Le syntaxe est la suivante :

```perl hl_lines="1 4-6"
use strict;
use warnings;

print "Comment vous appelez-vous ? ";
my $nom = <>; # Récupération du nom de l'utilisateur
chomp $nom;   # Retrait du saut de ligne
print "Bonjour, $nom !\n";
```

Début de la numérotation

Il est possible de spécifier le début de numération. Par exemple :

```python hl_lines="1 4" linenostart=10
def test(truc):      # Cette ligne est en évidence et est numérotée 10
    print truc         # Cette ligne est numéroté 11
                         # Cette ligne est numéroté 12
test("coucou")     # Cette ligne est en évidence et est numérotée 13
```

On utilise le mot-clé linenostart de la même façon que le hl_lines vu précédemment.

Code inline

Enfin, si vous souhaitez insérer un petit élément de code dans votre phrase (comme print par exemple), alors un seul accent grave autour du mot suffira :

comme `print` par exemple

Images

L’insertion d’une image ressemble à celle d’un lien, à ceci près que le texte d’ancrage doit être remplacé par un texte alternatif :

![Logo Creative Commons](https://mirrors.creativecommons.org/presskit/logos/cc.logo.png)

Il y a une petite différence de comportement selon que vous placiez votre image seule dans un paragraphe (ou dans un bloc de texte type citation, information, secret, etc.) ou bien au cours d’une phrase dans votre texte.

Lorsque l’image est seule, alors elle est présentée comme figure avec légende. Ainsi, si on prend l’exemple suivant :

Bla bla bla

![Logo Creative Commons](https://mirrors.creativecommons.org/presskit/logos/cc.logo.png)

Bla bla bla encore

Alors le rendu sera la suivant :

Bla bla bla

Bla bla bla encore

Si en revanche l’image est placée au cours d’un texte, alors le comportement sera plus classique et l’image apparaîtra naturellement dans la phrase :

Appuyez sur l'icône ![Icône machintruc](icone.png) et admirez le résultat.

Il est possible de définir à la fois un texte alternatif et une légende, en utilisant le mot-clé Figure de la même façon que pour les légendes de tableaux ou blocs de code :

Bla bla bla

![Mon super alt](logo.png)
Figure: Ma super légende !

Bla bla bla

Ainsi, le texte alternatif et la légende sont bien différents.

Vidéos

Les vidéos doivent être insérées avec une syntaxe dédié : !(URL Vidéo). Elles ne peuvent être inline (au sein d’une phrase).

Pour insérer une vidéo on peut donc faire :

Bla bla bla

!(https://www.youtube.com/watch?v=oavMtUWDBTM)

Bla bla bla

ou avec une légende :

Bla bla bla

!(https://www.youtube.com/watch?v=oavMtUWDBTM)
Video: Ma super légende

Bla bla bla

Par exemple :

Touches

Pour représenter une touche, utilisez deux barres verticales avant et après le nom de la touche :

Utilisez ||Ctrl|| + ||C|| pour copier.

Vous pouvez bien sûr mettre ce que vous voulez comme nom de touche.

Smileys

Que serait un forum sans smileys ? Un forum plus agréable ? Peut-être. Il n’empêche que les fameux smileys sont incontournables. Sur ZdS, les smileys que vous écrivez seront automatiquement transformés en image. Ci-dessous une liste (non exhaustive) des smileys disponibles :

Entrée	Résultat
:)
:D
;)
:p
:lol:
:euh:
:(
:o
:colere2:
o_O
^^
:-°
:ange:
:colere:
:diable:
:magicien:
:ninja:
>_<
:pirate:
:'(
:honte:
:soleil:
:waw:
:zorro:

N’oubliez pas : l’abus de smileys est dangereux pour votre santé et celle de vos proches, utilisez-les avec modération.

Balises attention, erreur, information, question et secret

Les tutoriels et articles de ZdS sont parsemés de balises telles que la balise "information" :

Elle se fait avec la syntaxe suivante :

[[information]]
| Ceci est une balise d'information.
|
| Cool, non ?

Ou dans sa version raccourcie :

[[i]]
| Ceci est une balise d'information.
|
| Cool, non ?

Les balises disponibles sont :

• attention
• erreur
• information
• question
• secret

La balise "secret" (appelée "spoiler" sur certains sites) a ceci de spécial qu’elle masque son contenu par défaut et ne le rend visible qu’au clic de l’utilisateur.

Citations

Les citations permettent de séparer votre propos de celui que vous rapportez. D’ailleurs, si l’on en croit ce vieux proverbe nous venant d’une petite planète quelque part aux confins de Bételgeuse, il ne faut pas s’en priver :

On utilise pour cela un chevron devant chaque début de ligne, avec optionnellement votre source, écrite de la même façon que les légendes (avec le mot-clé Source) :

> Ceci est une citation
> 
> sur plusieurs lignes
Source: Citez vos sources !

Blocs à titre et blocs neutres

Parfois vous désirez mettre en avant une information (par exemple un théorème) mais aucun des blocs spéciaux ne vous convient. Vous pouvez alors utiliser un bloc neutre.

Ce bloc aura forcément un titre, ce qui aidera à mettre le contenu en avant. Par exemple :

[[neutre | Théorème de Pythagore]]
| Un triangle ABC est rectangle en a si et seulement si $AB^2 + AC^2 = BC^2$

Notons que tous les autres blocs peuvent aussi avoir un titre, il se présente de la même manière, c’est-à-dire en mettant [[nom_du_bloc | titre du bloc]]. Ils ne sont par contre pas obligatoires.

Il est possible de mentionner des membres dans un message avec @pseudo ou @**pseudo-compose**. Ces membres recevront une notification, il ne faut donc pas en abuser !

Si ce paragraphe était écrit dans un message du forum ou un commentaire et que @pseudo ou @**pseudo-compose** existaient, ils recevraient une notification !

Pour éviter les abus, seulement les 15 premiers membres mentionnés dans le message reçoivent une notification.

Abréviations

Il est souvent utile de préciser la signification d’une abréviation (notamment d’un acronyme ou d’un sigle), sans toutefois la faire figurer dans le corps du texte. En utilisant la syntaxe suivante, la signification apparaîtra au passage de la souris sur l’abréviation :

Bienvenue sur ZdS !

*[ZdS]: Zeste de Savoir

Bienvenue, donc, sur ZdS !

Notes de bas de page

Toujours dans l’idée d’enrichir votre texte¹, vous pouvez utiliser des notes de base de page :

Markdown[^mdown] est une syntaxe légère d'écriture de documents. Pandoc[^pandoc] est un convertisseur de documents.

[^mdown]: Plus d'informations sur [Markdown](https://daringfireball.net/projects/markdown/).

[^pandoc]: Plus d'informations sur [Pandoc](https://pandoc.org/).

Les notes sont alors numérotées automatiquement. Vous n’avez à vous soucier que du nom que vous donner à votre note.

Si vous avez besoin d’écrire un caractère réservé entrant en conflit avec l’une des syntaxes décrites ici (l’astérisque par exemple), vous pouvez le faire en le précédent d’un antislash : \*

Enfin, vous pouvez mettre une partie de votre texte en commentaires en le mettant entre des balises spécifiques :

Ceci est mon texte. <--COMMENTS Et ceci est une partie commentée. COMMENTS--> 

La partie commentée n’apparaîtra tout simplement pas dans le rendu final.

Afin de vous aider à rédiger un contenu agréable à lire, le moteur markdown de zeste de savoir inclus un module de typographie automatique.

Cela signifie que certains caractères (par exemples les apostrophes anglais) seront remplacés par des caractères typographiquement corrects.

De même, nous nous occupons de mettre les espaces insécables aux bons endroits.

Lorsque vous écrivez une phrase longue, votre navigateur va automatiquement passer à la ligne une fois la limite atteinte. Pour faire cela, il va "couper" la phrase. Le meilleur endroit pour couper une phrase, c’est l’espace entre deux mots.

Mais voilà, il existe certaines règles de typographie qui rendent ce comportement gênant. Par exemple, lorsque vous vous préparez à faire une liste et que vous terminez votre phrase par :.

Logiquement, vous devez entourer votre caractère : d’espaces. Ce qui peut amener un cas étrange : votre phrase étant trop longue, votre navigateur met les : à la ligne.

C’est ce problème que résout l’espace insécable. Son nom elle ne l’usurpe pas : c’est une espace qui ne peut pas être coupée. En fait l’espace qui est avant les : doit être une espace insécable.

Le problème c’est que la majorité des claviers et des systèmes d’exploitation n’ont pas de moyen simple de faire cette espace. Et c’est pourquoi nous la faisons pour vous. En plus ça vous évitera de vous demander quels types et combien d’espaces vous devez mettre autour d’un signe de ponctuation.

Aide mémoire :