Vous avez peut-être déjà entendu parler du Markdown, vous en avez certainement même lu sans savoir ce que c’était, sa simplicité le rendant de plus en plus populaire. Si vous avez déjà créé ou documenté un plugin WordPress vous en avez déjà manipulé. Certains sites ou forums tels que OpenClassrooms par exemple permettent aussi de publier du contenu sous ce format, une grande majorité des projets partagés sur GitHub contiennent un ficher readme à ce format… Bref, il ne s’agit pas d’un obscur pseudo language qui sera oublié la semaine prochaine. Si vous voyez ce terme pour la première fois, je vous propose de le découvrir en quelques lignes. Si vous êtes plus à l’aise avec ce langage vous pouvez utiliser cet article comme un aide mémoire pour la syntaxe.
Qu’est ce que le Markdown ?
Il s’agit d’un langage de balisage (comme le html) créé en 204 par John Gruber et Aaron Swartz pour offrir une syntaxe facile à écrire.
Un texte rédigé en Markdown peut être converti en html pour être affiché de façon enrichie, mais sa principale source d’inspiration étant l’email en mode « texte brut » il doit pouvoir être lu avec n’importe quel éditeur de texte sans que la strutcure du document ne devienne floue ou illisible.
Syntaxe du Markdown
Comme en html, le langage Markdown utilise un certain nombre de « balises » qui permettent de structurer et de présenter la texte, voici les principales :
Les titres
Le html propose 6 niveaux de titre (de h1 à h6), le Markdown reprend cette possibilité de la façon suivante :
# Titre de niveau 1 ## Titre de niveau 2 ### Titre de niveau 3 #### Titre de niveau 4 ##### Titre de niveau 5 ###### Titre de niveau 6
Noez qu’il est aussi possible d’utiliser les signes = et – pour indiquer respectviement un titre de niveau 1 et un tire de niveau 2. Il suffit de souligner le texte de cette façon :
Titre de niveau 1 ================= Titre de niveau 2 -----------------
Le nombre de caractères importe peu, il suffit juste de souligner le texte. Néanmois, si vous avez déjà utilisé du [reStructuredText] vous aurez l’habitude d’utiliser autant de = ou – qu’il y a de signes dans votre titre, en plus c’est plus joli comme ça quand vous utilisez une police non proportionnelle.
Les paragraphes et fin de ligne :
Pour créer un paragraphe, il suffit de séparer votre texte à l’aide d’une ligne vide, comme ceci
pagragraphe 1, pas très long
paragraphe 2, plutôt court lui aussi
Pour obtenir un simple saut de ligne, il faut terminer chaque ligne par 2 espaces, même si ça ne se voit pas avec un simple bloc-notes. Sans cela, le texte ci-dessous serait interprété comme une seule ligne
Autrefois le Rat de ville Invita le Rat des champs, D’une façon fort civile, A des reliefs d’Ortolans
Les LISTES
Comme en html, il est possible de faire des listes à puce (en commençant vos lignes par un des caractères suivant : *, +, -) ou numérotées (en commençant vos lignes par un numéro et un point). Il est aussi possible d’imbriquer les listes à puce, simplement en indentant vos listes.
* Item 1 * Item 2 * Item 2.1 * Item 2.2 * Item 3
1. Item 1 2. Item 2 3. Item 3
Le format Markdown permet aussi de créer des définitions ou listes de définition. Le terme défini est suivi par un retour à la ligne et deux points. Il est possible d’avoir plusieurs définitions pour un terme et plusieurs termes pour une seule définition
Responsive Mind
: Un blog fantastique
Renaud Mariage-Gaudron : Un bloggeur fantastique : Un chef de projets formidable
Communication digitale Marketing Développement Web : Un travail passionnant
Mettre du texte en avant : le gras et l’italique :
Il suffit d’utiliser au choix un (texte important) ou deux (texte très important) des caractères * ou _ (underscore) pour mettre du texte en avant
Texte *important* en italique Texte _important_ en italique Texte **très important** en gras Texte __très important__ en gras
Caractères spéciaux
Il arrive forcément un moment où l’on veut écrire un des caractères réservés pour la syntaxe, il suffit pour cela de le faire précéder d’un \ (antislash)
Je veux afficher une \*
Les caractères à échapper sont les suivants
- \ antislash
- ` accent grave
- * étoile
- _ underscore
- {} accolades
- [] crochets
- () parenthèses
- # dièse
- + plus
- – moins
- . point
- ! point d’exclamation
Citation et codes
Comme dans la majorité des clients de messagerie électronique, la citation en Markdown se fait simplement en insérant un symbole > (supérieur) en début de chacune des lignes de la citation.
> La misère des amis n'est pas plus amusante
> que la vue d'un jardin dont la flore est mourante
Pour intégrer du code html, il suffit … de l’écrire tel qu’il est
Il n'y a <big>rien</big> de particulier à faire
Pour insérer un exemple de code, quel que soit le language, il faut simplement l’indenter, c’est-à-dire le décaler de 4 espaces ou d’une tabulation
Voici un code javascript très complexe :
<script> alert('rouge'); </script>
Pour insérer un tout petit bout de code à l’intérieur d’une ligne, c’est l’accent grave qu’il faut utiliser.
Sinon tu fais un `print_r` pour voir le contenu du tableau
Liens hypertexte
Par rapport au html l’ordre de l’anchor text et de l’url est inversé, ça semble logique mais ça m’a joué quelques tours au début… Le texte est signalé par des accolades et l’url par des parenthèses.
[anchor texte](url)
[Le meilleur blog du monde](http://www.responsive-mind.fr)
IMAGES
Il s’agit d’un lien hypertexte avec un point d’exclamation devant. Notez qu’il est possible d’ajouter un titre à l’image en l’inscrivant entre guillemets doubles dans les parenthèses destinées à l’url de l’image
Image avec un lien hypertexte
La meilleure solution (selon ce forum) semble être de combiner l’image et le lien de la façon suivante
[![alt text][2]][1] [1]: http://meta.stackoverflow.com/users/44330/jason-s [2]: http://www.gravatar.com/avatar/dd57e..dfd07?s=128&d=identicon&r=PG (hover text)
Mais vous trouverez certainement d’autres solutions fonctionnelles, n’hésitez pas à les partager dans les commentaires.
Barre de séparation, filet horizontal
Rien de compliqué, répétez un tiret haut ou une étoile et voilà.
--------
********
TABLEAUX
Encore une fois c’est simple mais efficace : un pipe permet de séparer les colonnes et une ligne de tiret hauts permet d’isoler la ligne d’en-tête. Vous noterez que le résultat est plus agréable à l’oeil si vous utilisez une police non proportionnelle : vous pouvez ajuster la largeur des colonnes en insérant des espaces après leur contenu.
Article | Qté --------------- Marteau | 1 Clous | 100
Notes de bas de page
Il suffit d’insérer le numéro de la note précédé d’un accent circonflexe, et encadre par des crochets à l’endroit où la note doit être insérée, puis de recommencer en bas de page pour saisir le commentaire en question.
Cet article écrit par une personne formidable [^1] résume à lui tout seul toute la complexité de cet art séculaire[^2].
[^1]: Moi, bien sur
[^2]: Vous aussi vous pouvez utiliser un pipeautron ou recycler les spams reçus dans vos commentaires
Interpréter du Markdown en PHP ?
En théorie le Markdown n’a pas besoin d’être interprété par un logiciel pour être compris par un humain, cela dit c’est quand même plus agréable de visualiser du texte avec un miminum de mise en forme. Les outils pour cela sont légions mais je vous propose de commencer par parsedown.org, une librairie php dont vous pouvez avoir une démonstration sur le site officiel : http://parsedown.org/demo, qui vous montrera d’un simple coup d’oeil pourquoi je vous conseille cet outil : sa rapidité.
Son usage est très simple :
- téléchargez le fichier Parsedown.php
- renommez-le en parsedown.php (parce que les majuscules dans les noms de script c’est pas l’idéal)
- incluez le script dans votre code
- instanciez un objet Parsedown
- utilisez l’objet pour interpréter votre texte en markdown
Voici un exemple en 3 lignes :
Vous pouvez aussi jeter un coup d’oeil à la bibliothèque PHP Mardown, mais pour ma part, parsedown fait le job comme il faut.
Vous voilà maintenant aguéris, ou au moins initiés à ce langage, j’espère que cet article au format un peu « dictionnaire » vous sera utile, notamment aux nombreux développeurs qui suivent ces pages (merci l’étude des centres d’intérêt dans Google Analytics). Comme d’habitude, tous vos retours d’expérience et toutes vos astuces sont les bienvenus dans les commentaires ci-dessous.
Si vous avez aimé cet article, vous aimerez peut-être
Sources :
Documentation officielle: http://daringfireball.net/projects/markdown/syntax
Crédit logo: http://dcurt.is/the-markdown-mark