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

![Logo Responsive Mind](http://www.responsive-mind.fr/logo.png "titre optionnel")

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 :

include 'parsedown.php';
$objet_parsedown = new Parsedown();
echo $objet_arsedown->text('Hello _World_!');

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.

Sources :

Documentation officielle: http://daringfireball.net/projects/markdown/syntax
Crédit logo: http://dcurt.is/the-markdown-mark