Zeste de Savoir utilise un langage de formatage de texte très proche du Markdown, auquel ont été ajoutés quelques extensions courantes. Ce langage est utilisé sur ZdS pour écrire les tutoriels, les articles, les messages de forums ou MP, etc.
On ne présente plus le Markdown, ce langage de formatage alliant la simplicité d'écriture à la facilité de lecture. Sa syntaxe très légère permet en effet de lire du simple texte de façon presque aussi agréable que s'il était réellement mis en forme. Mais aussi pratique soit le Markdown, il ne permet pas de tout baliser. Les indices et exposants par exemple, n'ont pas de représentations Markdown. Il existe donc des extensions permettant de compléter le Markdown natif. Certaines de ces extensions, très courantes, ont été reprises sur ZdS, d'autres ont été spécifiquement implémentées pour répondre aux besoins précis de ZdS. Nous vous présentons donc ici les syntaxes utilisables sur ZdS.
Mise en forme de texte classique
Paragraphes
Les paragraphes s'écrivent naturellement, en sautant une ligne :
Ceci est mon premier paragraphe.
Ceci est mon second paragraphe.
Contrairement au Markdown standard, un retour à la ligne au sein d'un paragraphe sera bel et bien vu comme un retour à la ligne (et non pas comme un simple espace) :
Ceci est mon premier paragraphe.
Ici je reviens à la ligne, je suis toujours dans le premier paragraphe.
Ceci est mon second paragraphe.
Bref, écrivez vos paragraphes naturellement.
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 se font en précédent le texte d'un ou plusieurs croisillons selon leur niveau hiérarchique. 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
##### Titre de niveau 5
###### Titre de niveau 6
Six niveaux hiérarchiques sont possibles. 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.
[[attention]]
| Si la syntace avec underscore est utilisée en milieu de mot, alors le texte ne sera pas transformé. Ainsi truc_bidule_mush ne sera pas transformé alors que truc*bidule*mush le sera. La raison tient du fait que les expressions avec des underscores sont communes en informatique comme Mon_super_nom_de_fichier.txt par exemple.
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 soucis de simplicité et de lisibilité, vous ne pourrez pas mettre du texte en couleur, le souligner ou bien 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. Pour le centrer, on l'entoure de deux petites flèches (tiret et chevron) de directions inversées :
-> Ce texte est centré. <-
Pour l'aligner à droite, on utilise deux flèches dirigées vers la droite :
-> Ce texte est aligné à droite. ->
Enfin, sachez qu'il est impossible de justifier du texte sur ZdS.
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^10^ vaut 1024, alors on écrira :
2^10^ vaut 1024.
Pour l'indice, comme dans H~2~O par exemple, on utilise cette fois le tilde :
La molécule de l'eau est H~2~O.
Mise en forme avancée
Citations
Les citations permettent de séparer votre propos de celui que vous rapporter. 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 :
Les citations, c'est bien.
On utilise pour cela un chevron devant chaque début de ligne :
> Ceci est une citation
> sur plusieurs lignes
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 !
*[ZdS]: Zeste de Savoir
Notes de bas de pages
Toujours dans l'idée d'enrichir votre texte[^enrich], vous pouvez utiliser des notes de base de page :
[^enrich]: Sans pour autant l'alourdir.
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](http://daringfireball.net/projects/markdown/).
[^pandoc]: Plus d'informations sur [Pandoc](http://johnmacfarlane.net/pandoc/).
Les notes sont alors numérotées automatiquement. Vous n'avez à vous soucier que du nom que vous donner à votre note.
Tableaux et lignes
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 :
Nom
Age
Fred
39
Sam
38
Alice
35
Mathilde
35
De la même façon, pour faire une ligne horizontale comme ci-dessus, dessinez-là en utilisant (au moins) trois tirets :
------
Formules mathématiques
Une formule mathématique s'écrit à l'aide d'expressions TeX Math, en l'entourant de caractères dollars $ :
$a \cdot x^2 + b \cdot x + c = 0 \quad \Longrightarrow \quad x = rac {-b \pm \sqrt{b^2 - 4ac}}{2a}$
Ce qui donne :
$a \cdot x^2 + b \cdot x + c = 0 \quad \Longrightarrow \quad x = rac {-b \pm \sqrt{b^2 - 4ac}}{2a}$
Liens et emails
Il existe deux façons d'écrire des liens : avec ou sans texte d'ancrage.
Liens 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](http://www.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.
Liens présentés sous forme d'URL
Si vous ne souhaitez pas utiliser de texte d'ancrage et ainsi rendre une URL cliquable, alors vous n'avez rien à faire : une URL sera automatiquement cliquable.
Emails
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).
Vous pouvez également entourer l'email de chevrons pour le rendre cliquable :
Pour nous contacter : <contact@monsite.com>
Listes
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.
La syntaxe est tellement naturelle que je ne vous ferai pas l'affront de mettre des exemples.
Code
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 de, au moins, trois accents graves (```) ou de trois tildes (~~~), avant et après :
!/usr/bin/env python3
print("Hello, World!")
ou
!/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 ouvrant :
A noter qu'actuellement, seule cette syntaxe fonctionne pour imbriquer un bloc de code à l'intérieur d'un autre bloc (une citation par exemple) dû à des limitations du parseur markdown utilisé, mais nous sommes dessus !
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
Médias
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 :
Le texte alternatif doit être renseigné. Il sert à apporter la même information que l'image si celle-ci ne peut être chargée ou bien ne peut être vue (notamment pour les synthétiseurs vocaux pour les non-voyants).
Vidéos
Pour insérer une vidéo hébergée chez YouTube, Dailymotion ou encore Vimeo, indiquez simplement son URL dans un paragraphe à part. Le bloc vidéo correspondant sera alors automatiquement chargé.
Certains éléments de mise en forme sont spécifique à ZdS. Il aura tout de même fallu les implémenter, voici donc leur syntaxe.
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.
Balises attention, erreur, information, question et secret
Les tutoriels et articles de ZdS sont parsemés de balises telles que la balise "information" :
[[information]]
Ceci est une balise d'information.
Cool, non ?
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 pour effet de masquer son contenu par défaut et de ne le rendre visible qu'au clic :
[s]
| Ceci est un secret.
Caractères réservés
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 : \*
On ne présente plus le Markdown, ce langage de formatage alliant la simplicité d'écriture à la facilité de lecture. Sa syntaxe très légère permet en effet de lire du simple texte de façon presque aussi agréable que s'il était réellement mis en forme. Mais aussi pratique soit le Markdown, il ne permet pas de tout baliser. Les indices et exposants par exemple, n'ont pas de représentations Markdown. Il existe donc des extensions permettant de compléter le Markdown natif. Certaines de ces extensions, très courantes, ont été reprises sur ZdS, d'autres ont été spécifiquement implémentées pour répondre aux besoins précis de ZdS. Nous vous présentons donc ici les syntaxes utilisables sur ZdS.
Mise en forme de texte classique
Paragraphes
Les paragraphes s'écrivent naturellement, en sautant une ligne :
Contrairement au Markdown standard, un retour à la ligne au sein d'un paragraphe sera bel et bien vu comme un retour à la ligne (et non pas comme un simple espace) :
Bref, écrivez vos paragraphes naturellement.
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 se font en précédent le texte d'un ou plusieurs croisillons selon leur niveau hiérarchique. Ainsi un titre de premier niveau s'écrit avec un seul croisillon, un titre de deuxième niveau avec deux croisillons, etc.
Six niveaux hiérarchiques sont possibles. 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) :
ou
[[attention]] | Si la syntace avec underscore est utilisée en milieu de mot, alors le texte ne sera pas transformé. Ainsi
truc_bidule_mushne sera pas transformé alors quetruc*bidule*mushle sera. La raison tient du fait que les expressions avec des underscores sont communes en informatique comme Mon_super_nom_de_fichier.txt par exemple.Pour mettre du texte en gras le principe est le même, en doublant le symbole :
ou
Par soucis de simplicité et de lisibilité, vous ne pourrez pas mettre du texte en couleur, le souligner ou bien 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 :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. Pour le centrer, on l'entoure de deux petites flèches (tiret et chevron) de directions inversées :
Pour l'aligner à droite, on utilise deux flèches dirigées vers la droite :
Enfin, sachez qu'il est impossible de justifier du texte sur ZdS.
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^10^ vaut 1024, alors on écrira :
Pour l'indice, comme dans H~2~O par exemple, on utilise cette fois le tilde :
Mise en forme avancée
Citations
Les citations permettent de séparer votre propos de celui que vous rapporter. 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 :
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, donc, sur ZdS !
*[ZdS]: Zeste de Savoir
Notes de bas de pages
Toujours dans l'idée d'enrichir votre texte[^enrich], vous pouvez utiliser des notes de base de page :
[^enrich]: Sans pour autant l'alourdir.
Les notes sont alors numérotées automatiquement. Vous n'avez à vous soucier que du nom que vous donner à votre note.
Tableaux et lignes
Pour faire un tableau, la façon la plus simple est encore de le dessiner, à l'aide de barres verticales et de tirets :
L'exemple ci-dessus donnera donc :
De la même façon, pour faire une ligne horizontale comme ci-dessus, dessinez-là en utilisant (au moins) trois tirets :
Formules mathématiques
Une formule mathématique s'écrit à l'aide d'expressions TeX Math, en l'entourant de caractères dollars
$:Ce qui donne :
$a \cdot x^2 + b \cdot x + c = 0 \quad \Longrightarrow \quad x = rac {-b \pm \sqrt{b^2 - 4ac}}{2a}$
Liens et emails
Il existe deux façons d'écrire des liens : avec ou sans texte d'ancrage.
Liens 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 :
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.
Liens présentés sous forme d'URL
Si vous ne souhaitez pas utiliser de texte d'ancrage et ainsi rendre une URL cliquable, alors vous n'avez rien à faire : une URL sera automatiquement cliquable.
Emails
Les emails peuvent s'écrire de la même façon que les liens. Pensez simplement à ajouter la mention "mailto:" :
Vous pouvez également entourer l'email de chevrons pour le rendre cliquable :
Listes
Vous pouvez utiliser deux types de liste :
C'est peut-être la syntaxe la plus intuitive du Markdown ! Il suffit de matérialiser les puces par des tirets :
Ou bien par des chiffres :
Prenez simplement garde à bien sauter une ligne avant et après vos listes.
La syntaxe est tellement naturelle que je ne vous ferai pas l'affront de mettre des exemples.
Code
Bloc de code
Il n'est pas rare d'illustrer son propos d'un petit exemple de code :
Pour cela, il existe plusieurs solutions.
Première solution : entourer votre code de, au moins, trois accents graves (```) ou de trois tildes (~~~), avant et après :
!/usr/bin/env python3
print("Hello, World!")
ou
!/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 ouvrant :
Pour forcer le langage, utilisez cette fois trois symboles de deux points de suite :
A noter qu'actuellement, seule cette syntaxe fonctionne pour imbriquer un bloc de code à l'intérieur d'un autre bloc (une citation par exemple) dû à des limitations du parseur markdown utilisé, mais nous sommes dessus !
Code inline
Enfin, si vous souhaitez insérer un petit élément de code dans votre phrase (comme
printpar exemple), alors un seul accent grave autour du mot suffira :Médias
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 :
Le texte alternatif doit être renseigné. Il sert à apporter la même information que l'image si celle-ci ne peut être chargée ou bien ne peut être vue (notamment pour les synthétiseurs vocaux pour les non-voyants).
Vidéos
Pour insérer une vidéo hébergée chez YouTube, Dailymotion ou encore Vimeo, indiquez simplement son URL dans un paragraphe à part. Le bloc vidéo correspondant sera alors automatiquement chargé.
produira :
http://www.youtube.com/watch?v=oavMtUWDBTM
Spécifique ZdS
Certains éléments de mise en forme sont spécifique à ZdS. Il aura tout de même fallu les implémenter, voici donc leur syntaxe.
Touches
Pour représenter une touche, utilisez deux barres verticales avant et après le nom de la touche :
Vous pouvez bien sûr mettre ||ce que vous voulez|| comme nom de touche.
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 :
Ou dans sa version raccourcie :
Les balises disponibles sont :
La balise "secret" (appelée "spoiler" sur certains sites) a pour effet de masquer son contenu par défaut et de ne le rendre visible qu'au clic :
[s] | Ceci est un secret.
Caractères réservés
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 :
\*Sujet: http://127.0.0.1:8000/forums/sujet/4/rediger-sur-zestedesavoir/ Envoyé depuis Zeste de Savoir