Présentation
La syntaxe markdown, proche de la syntaxe wiki, permet de réaliser une mise en forme du texte assez simplement, en restant lisible. On la retrouve sur certaines applications comme Jupyter et son notebook et les développeurs habitués au service d'hébergement web Github savent que cette syntaxe est utilisée pour le fichier readme et les commentaires.
La syntaxe repose sur l'utilisation de caractères comme le dièse, l'étoile, le signe égal et d'autres facilement accessible sur le clavier. Le principe simple consiste comme tout langage de balisage à précéder ou entourer par un caractère spécial les mots et les phrases à mettre en forme. Pour certains effets, il est nécessaire de doubler ou tripler les caractères.
Quelques exemples
- La mise en italique se fait avec une étoile ou un souligné, soit en saisissant *italique* ou _italique_.
- La mise en gras se fait avec une double étoile ou un double souligné, soit en saisissant **gras** ou __gras__.
Il est possible de cumuler les deux effets avec 3 étoiles, 3 soulignés ou 1 étoile et 2 soulignés soit 3 caractères. - Pour les paragraphes, il suffit de laisser une ligne vide entre eux.
- Pour aller à la ligne dans un paragraphe, il suffit d'ajouter 4 espaces en fin de ligne.
- Pour les titres, il faut les faire précéder de #. Leur nombre donne le niveau de titre. Plus il y a de dièses, moins il est important.
- Les listes à puces se font simplement en faisant précéder chaque ligne par un tiret ou une étoile.
- Pour obtenir une liste numérotée, il suffit de faire précéder chaque item par un nombre suivi d'un point. Peu importe la valeur du nombre, la numérotation est recalculée automatiquement. On peut commencer chaque ligne par "0." .
- Pour finir, on peut insérer des liens hypertextes et des images.
Les possibilités sont grandes et de nombreux sites spécialisés vous éclaireront à ce sujet. Il suffit de taper markdown dans son moteur de recherche préféré. Néanmoins, je vous invite à consulter la page wikipédia de markdown.
Le codage informatique
L'intérêt de la syntaxe markdown est l'insertion de codes informatiques. Associé au plugin coloration syntaxique, les codes seront intégrés et mis en valeur dans le billet.
Premier exemple en HTML
<h1>Un titre de niveau 1</h1>
<p>un paragraphe</p>
Second exemple en langage Python
def moyenne(dico):
s,n=0,len(dico)
for e in dico:
s=s+dico[e]
return s/n
Quel usage sur Dotclear
Le premier usage est la possibilité de rédiger ces billets en utilisant la syntaxe markdown. Un second usage, qui me semble plus intéressant, réside dans la publication quasi immédiate de travaux déjà rédigés avec la syntaxe markdown tout en pouvant rapidement intégrer des extraits de codes informatiques. Cela concerne un public, peut-être restreint, dont les contenus sont essentiellement informatiques. C'est incontestablement un gain de temps pour la rédaction.
Un exemple pratique pour illustrer ce propos. Les utilisateurs de notebook Jupyter qui composent leurs documents, mélangent les énoncés avec des morceaux de codes informatiques. L'énoncé, déjà rédigé avec la syntaxe markdown n'a plus qu'a être copié et collé dans le billet. Pour le code informatique, il en est de même sauf qu'il faudra l'entourer des balises adéquates qui sont des triples quotes inversées ``` code ``` tout en indiquant le langage utilisé.
Exemple
#### Les balises HTML
Une balise est une lettre ou un mot compris entre deux chevrons < et > (symbole inférieur et supérieur).
Les balises sont:
- soit ouvrantes et fermantes,
- soit vides
**Exemple de balise html ouvrantes et fermantes**
```html
<h1>Balise de titre de niveau 1</h1>
<p>Balise de paragraphe</p>
```
**Exemple de balise html vides pour une image**
```html
<img src="mon_image.png" />
```
Le rendu sera le suivant :
Les balises HTML
Une balise est une lettre ou un mot compris entre deux chevrons < et > (symbole inférieur et supérieur).
Les balises sont:
- soit ouvrantes et fermantes,
- soit vides
Exemple de balise html ouvrantes et fermantes
<h1>Balise de titre de niveau </h1> <p>Balise de paragraphe</p>Exemple de balise html vides pour une image
<img src="mon_image.png" />
Deux remarques à propos de cet usage:
- Si on gagne du temps dans le copié/collé, il faut tout de même une lecture du document et apporter quelques modifications pour que l'affichage soit celui attendu.
- Le code informatique peut ne pas être bien parsé par le plugin. Il y a moyen d'utiliser le plugin coloration syntaxique (bouton avec les chevrons) qui solutionnera éventuellement le problème.
Comment rédiger avec la syntaxe markdown dans un billet
Dans l'espace de rédaction d'un billet, la colonne sur la droite propose différentes actions applicables au billet (publication, date, catégorie,...). Parmi elles, le formatage de texte vous permet de choisir votre syntaxe : xhtml, wiki et donc markdown.
Il suffit donc de sélectionner la syntaxe markdown et enregistrer le billet. Cela est simple mais pas suffisant pour que le billet soit correctement rédigé. Le choix de l'éditeur est important. Il faut surtout éviter l'éditeur dcCKEditor qui ne convient pas et ne comprend que la syntaxe xhtml. Le choix se portera sur l'éditeur dcLegacyEditor. Pour pérenniser ce choix, vous devez vous rendre dans l'espace Mes préférences et sélectionner l'éditeur dans l'onglet options.
Vous pouvez, si vous voulez rédiger tous vos billets en syntaxe markdown, modifier le format d'édition préféré avec la syntaxe markdown. Ainsi paramétré, vos billets seront correctement rédigés.
Conclusion
Ce billet a été entièrement rédigé avec la syntaxe markdown, les codes et les images ont été insérés selon cette syntaxe. L'enregistrement du billet a créé une version xhtml qui est affichée dans les navigateurs. S'il est édité à nouveau, la syntaxe markdown sera affichée et toute modification sera permise. Le contenu du billet est enregistré en deux exemplaires dans la base de données.
Les documents issues du Jupyter notebook sont faciles à insérer dans le blog dotclear grâce à ce plugin. Faites-en bon usage, intensif même, vos documents conserveront leurs qualités.
