Une introduction à Markdown

Réduction

Markdown est un outil de conversion de texte en HTML. Aujourd'hui, il est devenu le synonyme de facto d'une classe de langages de description de balisage légers. Il utilise une syntaxe de formatage de texte brut. L'idée derrière Markdown était de rendre la rédaction de pages Web et en particulier d'entrées de blog aussi simple que la rédaction d'un e-mail. Au mois de novembre 2017, l'objectif est atteint et Markdown ainsi que ses dérivations Asciidoc, Asciidoctor et Asciidoctor-pdf sont largement utilisés.

Markdown se concentre uniquement sur le texte brut et s'abstient de toutes les autres complexités que l'on trouve dans HTML. Il est facile à apprendre car il reste simple, donc aussi plus rapide car des caractères minimaux sont utilisés, ce qui réduit également les risques d'erreur à la fin. Voir la figure 1 pour un document de base affiché dans l'éditeur Markdown Stackedit. Sur le côté gauche vous voyez le code source et sur le côté droit la sortie HTML correspondante. Vous remarquerez peut-être que les titres sont simplement marqués d'un certain nombre de # en fonction du niveau hiérarchique du titre.

Conversion de texte

Le texte brut est convertible en XHTML (HTML) et de nombreux autres formats à l'aide des outils de ligne de commande comme Markdown ou Pandoc. Fondamentalement, les deux outils ne créent que des fragments HTML et écrivent la sortie sur stdout. Pandoc propose le commutateur "-o filename" pour écrire la sortie HTML dans le fichier donné. Comme on le voit ci-dessous, le fichier de sortie est nommé basic.html et contient le fragment HTML - deux titres et un paragraphe.

$ pandoc -o basique.html de base.md $ chat de base.html 
Comment créer un paquet Debian
 
Préface
 Être responsable d'une machine, c'est s'occuper aussi bien du matériel que des composants logiciels. Comme on le voit dans la vie de tous les jours en tant qu'administrateur système, il est bien préférable d'installer un logiciel en tant que progiciel plutôt qu'un tas de fichiers source. Cela réduit les coûts pour entretenir correctement le système. $ 

Pour créer des documents HTML autonomes avec un en-tête HTML complet, Pandoc accepte le commutateur « -s » comme suit :

$ pandoc -o basique.html -s basique.md $ chat de base.html           
Comment créer un paquet Debian
 
Préface
 Être responsable d'une machine, c'est s'occuper aussi bien du matériel que des composants logiciels. Comme on le voit dans la vie de tous les jours en tant qu'administrateur système, il est bien préférable d'installer un logiciel en tant que progiciel plutôt qu'un tas de fichiers source. Cela réduit les coûts pour entretenir correctement le système.   

L'avantage de garder le contenu séparé de votre affichage visuel est qu'il ne gâchera pas l'apparence de votre site. Version 1.0.1, qui a été développé par John Gruber et Aaron Swartz est sorti en décembre 2004 et est disponible en tant que logiciel gratuit (voir les liens à la fin de cet article).

Éléments de texte

Titres

Selon le niveau HTML correspondant, les titres sont écrits avec un certain nombre de # comme suit :

# H1 ## H2 ### H3 #### H4 ##### H5 ###### H6 

Pour H1 et H2, deux modes d'écriture alternatifs sont acceptés :

H1 == H2 -- 

Veuillez noter que le nombre de signes ou de tirets égaux doit correspondre au nombre de caractères du titre.

Mettre du texte en évidence

Afin de mettre l'accent sur le texte, ces éléments sont pris en charge :

• italique : astérisques simples ou traits de soulignement simples
  --
  *important* et _aussi important_
  --
• texte en gras : doubles astérisques ou doubles traits de soulignement
  --
  **important** et __aussi important__
  --
• texte barré : double tildes
  --
  ~~texte~~
  --

Listes

Markdown prend en charge les listes non ordonnées et ordonnées. Les listes ordonnées commencent par un astérisque, un signe plus ou un signe moins. Les listes ordonnées commencent juste par un chiffre. Pour créer des sous-listes, indentez l'élément de liste de deux espaces (Markdown, StackEdit) ou de quatre espaces (Pandoc) comme vous le voyez ci-dessous :

1. fruits * pomme * banane 2. boissons + eau + lait 

Images

Le moyen le plus simple consiste à utiliser le style en ligne comme suit :

![Le logo Debian](debian-logo.png « Logo Debian ») 

Cela affiche l'image référencée. Dès que vous déplacez le pointeur de la souris sur l'image, vous voyez le texte de description correspondant.

Mise en évidence du code et de la syntaxe

Il existe deux variantes - le code en ligne et les blocs de code. Le code en ligne est encadré de trois backticks comme "' print ("Bonjour, monde!")"'. Les blocs de code commencent et se terminent également par trois backticks mais sur des lignes séparées comme suit :

"imprimer ("Bonjour, monde!")"

Markdown ne prend pas en charge la coloration syntaxique, mais les dialectes comme Markdown Here le font.

les tables

Markdown ne prend pas en charge les tables mais les extensions comme GFM et Markdown Here le font.

Blockquotes

Les guillemets commencent juste par un signe ">". Il devient assez pratique de citer du texte.

> "Ah! il est absurde d'avoir une règle stricte sur ce qu'il faut > lire et ce qu'on ne doit pas lire. Plus de la moitié de la culture moderne dépend > de ce qu'il ne faut pas lire." > > L'importance d'être sérieux. (Oscar Wilde) 

Liens

Les liens renvoient à d'autres documents ou à des sections du document actuel. Le style d'écriture est similaire aux images et se compose de la description du lien entre crochets et de l'URL entre parenthèses régulières.

[Je suis un lien de style en ligne](https://linuxhint.com) 

De plus, vous pouvez ajouter un texte alternatif :

[Je suis un lien de style en ligne avec du texte supplémentaire](https://linuxhint.com "LinuxHint") 

Les liens peuvent être référencés comme suit :

[LinuxHint][1]… du texte… [1] : https://linuxhint.com 

Cela vous permet de construire facilement des listes de références à la fin de votre document comme c'est courant dans les documents scientifiques.

Conclusion

Markdown est assez simple et indispensable pour tous ceux qui font de la documentation et publient régulièrement du contenu. C'est un grand plaisir de l'utiliser.

Les références

• StackEdit, https://stackedit.io/éditeur
• Pandoc, http://pandoc.org/
• Markdown, https://daringfireball.net/projets/démarche/
• Aide-mémoire Markdown, https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet