Dans cette section de la documentation, nous détaillons la manière dont le contenu du site doit être rédigé.
Lorsqu’un lecteur se connecte sur le site EcriSoi, il consulte des pages web dont le format est le HTML. Mais vous n'avez pas besoin de connaître ce langage pour rédiger des articles.
Stylo, et donc EcriSoi, autorisent la structuration des informations depuis le Markdown. Lorsque vous publiez un article, TowSty, le logiciel écrit en Julia au cœur d'EcriSoi, transforme alors tous les articles rédigés depuis Mardown vers HTML. L'intérêt du Markdown est qu'il s’agit d'un langage dont les éléments de syntaxe sont plus simples et moins visibles que dans le cas du HTML, par exemple. Il n'est donc pas nécessaire de connaître des balises pour rédiger des contenus. Le Markdown utilise ses propres signes.
Nous ne couvrons pas ici l'intégralité des éléments de syntaxe Markdown. Nous renvoyons à cette documentation : https://stylo-doc.ecrituresnumeriques.ca/fr/tutoriels/syntaxemarkdown/.
À tout moment, vous pouvez vérifier que votre syntaxe est bien interprétée par Stylo. Utilisez pour cela la fonction Aperçu disponible lorsque vous rédigez un article.
Principes généraux du Markdown
Le Markdown a été conçu pour vous permettre de taper du texte d'une manière qui soit la plus naturelle possible, c'est-à-dire comme vous le feriez depuis un traitement de texte ordinaire, tel que Microsoft Word. Les éléments de structuration d'un document ne sont pas réalisés à la souris, en attribuant un titre ou en mettant en gras une portion de texte. Toutes les opérations de mise en forme du texte se font grâce à un certain nombre de signes diacritiques réservés.
Les paragraphes
Commençons par les paragraphes. Vous pouvez taper du texte directement dans la fenêtre d'édition de Stylo. Comme monsieur Jourdain, vous utilisez alors du Markdown sans même le savoir, puisque vous rédigez ici un paragraphe de texte qui est bien reconnu comme un paragraphe.
Les espaces sont signifiantes dans le Markdown. Lorsque vous décidez de rédiger un autre paragraphe, appuyez deux fois sur la touche Entrée de votre clavier et continuez de taper, exactement comme vous le feriez avec votre traitement de texte habituel.
Si vous ne tapez pas deux fois sur Entrée, le texte est alors considéré comme un seul paragraphe.
Retour à la ligne
Nous avons vu qu'en Markdown les espaces sont signifiantes et que la touche entrée de notre clavier permet de produire un nouveau paragraphe. Il est également possible de marquer un retour à la ligne sans signifier qu'il s'agit d'un nouveau paragraphe. À cette fin vous pouvez utiliser le caractère barre oblique inverse \, appelé aussi ___antislash___ en anglais, là ou vous souhaitez insérer ce retour à la ligne. Ce cas de figure s'est présenté dans l'extrait du premier cahier de Gabriel Tarde que nous avons cité précedemment.
s'être développé en profondeur, l'esprit doit se développer en étendue.\
Mais si l'étude du droit, scientifiquement et historiquement
(~~illis~~.)Vous pouvez ainsi procéder pour un texte en vers par exemple :
MONSIEUR JOURDAIN.\
Non, non, point de vers.
LE MAÎTRE DE PHILOSOPHIE.\
Vous ne voulez que de la prose ?
MONSIEUR JOURDAIN.\
Non, je ne veux ni prose ni versVous obtiendrez alors le rendu suivant dans Stylo :
Il s'agit de l'équivalent de <br> en HTML qui fonctionne d'ailleurs aussi à la place de la barre oblique inverse et que vous pouvez utiliser également dans Stylo.
Les niveaux hiérarchiques
Nous pouvons à présent entrevoir une distinction importante. Avec Stylo et le Markdown, tant que vous n'appuyez pas sur le bouton d'aperçu de l'interface, vous ne voyez pas complètement le résultat de ce que vous tapez. Et c'est encore plus vrai avec EcriSoi, puisque TowSty produit un texte bien différent encore lorsque vous le publiez sur le site.
Il est donc important de bien structurer son document. À cette fin, le Markdown s'appuie sur un certain nombre de caractères accessibles facilement. Les titres sont des niveaux hiérarchiques. Tous les I., II. et III. d'un document appartiennent au même niveau hiérarchique, celui des titres de partie. Le A. du I. et le C. du III., au sein d'un plan très général comme celui qui suit, appartiennent également à un même niveau de titre qui est celui des sous parties.
I.
A.
B.
C.
II.
A.
B.
C.
III.
A.
B.
C.
En Markdown, les niveaux hiérarchiques et donc les titres sont signifiés par le caractère dièse #. Pour préciser un titre, il suffit donc d'écrire ce signe suivi d'une espace, puis de l'intitulé. Par exemple :
# Une première partieL'espace est très importante. Le titre n'est pas reconnu comme un titre si elle n'est pas présente.
Pour placer une sous partie, ou même une sous sous partie, il suffit de multiplier les dièses les uns à la suite des autres sans espace et de préciser le titre ensuite. Ainsi :
## Une sous partie
### Une sous sous partie
#### Une sous sous sous partie
##### Une sous sous sous sous partie
###### Une sous sous sous sous sous partieCette façon de procéder en multipliant les # vous permet de préciser tous vos niveaux de titre.
Attention : avec Stylo, il est recommandé de commencer la structuration au niveau ##. Notre plan type devient donc :
## Un titre
### Une sous partie
### Une autre sous partie
### Encore une autre sous partie
## Un autre titre
### Une sous partie
### Une autre sous partie
### Encore une autre sous partie
## Encore un autre titre
### Une sous partie
### Une autre sous partie
### Encore une autre sous partieL'enrichissement des caractères
Il existe plusieurs façons de mettre votre texte en gras ou en italique. Les caractères réservés sont soit l'astérisque * soit le tiret bas _.
L'italique
Si vous souhaitez mettre un mot ou une portion de texte en italique, il vous suffit de l'encadrer par l'un de ces deux signes au choix sans espace.
un mot en _italique_
un autre mot en *italique*
un paragraphe en italique : _Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Sed non risus. Suspendisse lectus tortor, dignissim
sit amet, adipiscing nec, ultricies sed, dolor. Cras elementum ultrices
diam. Maecenas ligula massa, varius a, semper congue, euismod non, mi.
Proin porttitor, orci nec nonummy molestie, enim est eleifend mi, non
fermentum diam nisl sit amet erat. Duis semper. Duis arcu massa,
scelerisque vitae, consequat in, pretium a, enim. Pellentesque congue.
Ut in risus volutpat libero pharetra tempor. Cras vestibulum bibendum
augue. Praesent egestas leo in pede. Praesent blandit odio eu enim.
Pellentesque sed dui ut augue blandit sodales. Vestibulum ante ipsum
primis in faucibus orci luctus et ultrices posuere cubilia Curae;
Aliquam nibh. Mauris ac mauris sed pede pellentesque fermentum.
Maecenas adipiscing ante non diam sodales hendrerit._Le gras
Pour le gras, il vous suffit de doubler ce signe :
un mot en __gras__
un autre mot en **gras**Si jamais vous souhaitiez obtenir du gras et de l'italique, il vous suffit de tripler le signe de votre choix.
un mot en ___gras et en italique___Barrer un mot
Il est également possible de barrer une expression. Cette fonction est très utilisée lorsque l'on souhaite transcrire un manuscrit notamment. Comme pour l'italique ou le gras, il suffit de placer avant et après le terme de deux caractères tilde consécutifs sans espace ~~A~~
Ce cas de figure se présente dans l'Ego Corpus consacré à Gabriel Tarde. Ainsi, au sein du premier cahier, ligne 77, on trouve l'expression :
s'être développé en profondeur, l'esprit doit se développer en étendue.\
Mais si l'étude du droit, scientifiquement et historiquement
(~~illis~~.)Les hyperliens et les images
Les hyperliens, c'est-à-dire les liens au sein des pages web qui renvoient vers d'autres pages, et les images ont une syntaxe très proche. En effet, il faut faire suivre deux crochets [] de deux parenthèses () et cela sans espace entre ces signes. Par convention, il faut placer entre crochets l'ancre, le mot ou l'expression qui apparaît sur la page et sur lesquels on peut cliquer. La cible, la page vers laquelle nous sommes renvoyés, est indiquée entre parenthèses.
Pour renvoyer vers le site EcriSoi par exemple, il faut alors taper en Markdown :
[Lien vers le site EcriSoi](https://ecrisoi.univ-rouen.fr/)qui donne :
Pour les images la syntaxe est identique. Il faut simplement rajouter un point d'exclamation devant le crochet pour signifier qu'il faut afficher une illustration :
sera rendu comme :
Nous avons déjà vu la syntaxe Markdown pour insérer des images dans un article. Les images peuvent apparaître trop grande pour une page du site. Il est heureusement possible d'en réduire les dimensions. Pour cela, il suffit d'ajouter après le Markdown les dimensions souhaitées en pourcentage entre accolades. Par exemple :
{width=20%}permet d'afficher cette illustration avec seulement 20% de ses dimensions originales.
Les images du site sont normalement stockées sur Nakala. Une fois que vous ajoutez votre illustration à une donnée, utilisez bien l'adresse produite par le bouton « Copier l'url de téléchargement » (ou « Copy download url » si votre espace Nakala est en anglais).
Les notes
Il est bien évidemment possible de faire des notes de bas de page en Markdown. Il existe là encore deux méthodes.
- Vous pouvez rédiger l'intégralité de votre note à la suite du terme sur lequel porte cette note.
La syntaxe est alors composée du caractère de l'accent circonflexe suivi sans espace des crochets ^[]. Le contenu de la note est alors rédigé entre ces crochets .
Le Markdown permet de placer des notes partout où on le souhaite^[C'est vraiment pratique.].- Vous pouvez aussi placer toutes vos notes à la fin de votre document.
Dans ce cas, vous devez taper votre appel de note dans le fil de votre paragraphe accolé à un terme de votre choix auquel la note renvoie.
La syntaxte de cet appel est constituée de deux crochets à l'intérieur desquelles l'appel lui-même est identifié par un accent circonflexe suivi d'un identifiant [^identifiant].
L'identifiant doit être reservé à un seul appel de note et à une seule note. Il ne doit donc pas être réutilisé pour une autre note. Il identifie une note et son appel et permet de générer le bon renvoi lors de la transformation en HTML.
Vous pouvez attribuer des chiffres ou même du texte sans espace [^1], [^a] ou [^terme].
La note elle-même doit être placée à la fin du document. Elle doit reprendre le même identifiant entre crochets que l'appel. Il suffit alors de faire suivre cette référence du signe de ponctuation double :. Le texte de la note est rédigé après ces deux points suivi d'une espace.
[^1]: Une note.Ce qui donne :
Lorem ipsum dolor sit amet[^1], consectetur adipiscing elit.
Sed[^sed] non risus. Suspendisse lectus tortor, dignissim
sit amet, adipiscing nec, ultricies sed, dolor. Cras elementum
ultrices diam. Maecenas ligula massa, varius a, semper
congue, euismod non, mi.
[^1]: Une note avec un chiffre.
[^sed]: Une note depuis un mot.
Les citations
Il est bien évidemment possible d'insérer des citations à la suite d'un paragraphe. Pour cela, après avoir tapé les deux retours à la ligne avec la touche entrée, il est possible d'introduire un bloc de citation avec le signe supérieur à pleine chasse > suivi d'une espace.
> Une citationC'est par exemple le cas dans l'article « Une place pour l’autofiction dans le dévoilement politique de l’intime ? » depuis Critique/Entretiens du site EcriSoi :
> Ce qui se produit dans une relation amoureuse, affective ou sexuelle ne
regarde certes pas l'État au sens où il aurait à légiférer sur la
légitimité des désirs. Il est en revanche à sa charge de garantir que de
tels liens soient institutionnellement possibles et puissent se déployer
à l'abri du jugement social^[Michaël Fœssel, _La Privation de
l'intime_, _op. cit._, p. 140.].Les pseudo-classes
La syntaxe Mardown est riche et permet déjà beaucoup. Seulement, il arrive que nous souhaitions un certain traitement spécifique, un certain rendu qui ne serait pas pris en charge nativement par le Mardown. Comment aligner du texte à droite par exemple ? Comme changer la taille de mon illustration ? Pour toutes ces questions, et bien d'autres, il est possible d'aller encore plus loin dans la grammaire proposée. Nous détaillons donc ici des éléments de syntaxe facultatifs qui permettent d'obtenir le résultat souhaité. Ces éléments sont propres au site EcriSoi.
Propriétés avancées de caractères et de paragraphes
Il existe donc, aux côtés des éléments de syntaxe Mardown que nous avons déjà examinés, des suites de caractères dont la syntaxe est un peu plus complexe. Nous appellerons ici ces éléments des pseudo-classes, en référence au HTML et au CSS. La syntaxe de ces pseudo-classes peut apparaître étrange. Mais ces dernières sont conçues justement pour ne pas être confondues par Stylo et TowSty avec le reste du texte de votre paragraphe.
La syntaxe générale est de taper trois signes appelés « deux-points » sans espace puis deux accolades qui encadrent un point suivi sans espace du nom de la pseudo classe : ::: {.nom_de_la_pseudo_classe}.
Propriétés de paragraphes
L'alignement
Ces pseudo-classes vous permettent de modifier l'alignement du texte. Par défaut dans EcriSoi, le texte est justifié. Mais dans certaines occasions, il se peut que vous ayez besoin d'aligner le texte à droite ou au centre. Il existe alors deux pseudo-classes qui vous permettent de réaliser ce rendu :
::: {.alignRight}
::: {.alignCenter}Pour les utiliser, vous devez placer votre texte après cette pseudo-classes, suivi d'un retour à la ligne effectué en appuyant une fois sur la touche Entrée. À la fin du paragraphe sur lequel vous souhaitez faire porter cette pseudo-classes, vous devez taper de nouveau trois fois le signe « deux-points » sans espace ::: après un retour à la ligne.
Ce qui donne pour ::: {.alignRight}
:::{.alignRight}
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Sed non risus. Suspendisse lectus tortor, dignissim sit
amet, adipiscing nec, ultricies sed, dolor. Cras elementum
ultrices diam. Maecenas ligula massa, varius a, semper
congue, euismod non, mi. Proin porttitor, orci nec
nonummy molestie, enim est eleifend mi, non fermentum diam
nisl sit amet erat. Duis semper. Duis arcu massa, scelerisque vitae
:::La syntaxe est la même pour ::: {.alignCenter}.
La numérotation des paragraphes
Par défaut, les paragraphes de textes sont numérotés de façon à en faciliter la citabilité. Il est cependant possible d'interrompre cette numérotation grâce à une pseudo-classes spécifique ::: {.numberOff}.
Paragraphe numéroté
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation
ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. Excepteur
sint occaecat cupidatat non proident, sunt in culpa qui
officia deserunt mollit anim id est laborum.""Lorem ipsum
dolor sit amet, consectetur adipiscing elit,
::: {.numberOff}
Paragraphe non numéroté
:::
Paragraphe numéroté
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation
ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. Excepteur
sint occaecat cupidatat non proident, sunt in culpa qui
officia deserunt mollit anim id est laborum.""Lorem ipsum
dolor sit amet, consectetur adipiscing elit,Comme ces propriétés avancées ont été spécialement réalisées pour le site EcriSoi. Vous ne pourrez donc malheureusement pas utiliser la fonction de prévisualisation propre à Stylo pour en apprécier le résultat. Mais normalement, une fois l'article publié sur le site, vous pourrez constater qu'elle a bien été appliquée.
<!– @rmq illustration à ajouter –>
Propriétés de caractères
De la même manière, vous pouvez avoir besoin ponctuellement de traiter un mot d'une certaine manière que le Mardown ne prévoit pas nativement. C'est le cas de la petite capitale et du soulignement. À cette fin, il existe deux pseudo-classes. Leur fonctionnement est proche des deux précédentes. La pseudo classe doit être précisée entre accolades suivie d'un point. L'expression sur laquelle porte cette pseudo-classe doit être précisée entre crochets [mot sur lequel porte la pseudo classe]{.nom_de_la_pseudo_classe}. Il n'y a pas d'espace entre les crochets et les accolades.
Pour la petite capitale, vous pouvez ainsi utiliser :
[un nom propre]{.smallcaps}Pour du texte souligné, vous pouvez ainsi taper :
[une expression]{.underline}`La transformation est effectuée lors de la publication.
Le fond et la forme
Au terme de cette introduction à la rédaction des articles pour le site EcriSoi, peut-être n'est-il inutile de préciser ici la manière dont les pages sont produites.
Tous les articles sont donc rédigés en Markdown depuis Stylo. Nous examinons dans un article dédié la question de la publication.
Lorsque vous prévisualisez votre texte dans Stylo, celui-ci se voit automatiquement attribué un style. Votre texte obtient une certaine taille de police qui n'est pas la même pour les différents niveaux de titre par exemple. De la même manière, l'alignement du texte dans ce rendu est fixé par Stylo. Nous pouvons dire que les données textuelles sont traitées d'une certaine manière.
Ce traitement s'opère grâce à un langage spécifique que l'on appelle le CSS. C'est ce langage qui précise la couleur du texte, sa taille ou même le type de police.
Il en va de même pour le site EcriSoi. Afin de s'approcher au plus près de notre modèle, nous avons développé un style spécifique pour le site en CSS.
L'aperçu depuis Stylo n'est donc pas celui que vous obtiendrez sur le site EcriSoi.