FLASH INFORMATIQUE FI



Markdown


Markdown est un langage de balisage léger qui permet d’écrire simplement du texte et de le convertir en code HTML pour sa publication sur un site web. Facile à lire, facile à écrire.



Markdown is a small markup language that allows you to write text (without tags) and convert it into HTML for publication on a website. Easy to read, easy to write.


Nicolas BORBOËN


Fiche descriptive


Introduction

Markdown est un simple langage de balisage humain fondé sur l’expertise des conversions de texte brut de toute l’histoire de l’informatique. Il a été écrit par John Gruber, qui édite le site http://daringfireball.net, aidé d’Aaron Swartz (voir encart). C’est un petit (18KB) logiciel libre, diffusé sous licence BSD et sa version actuelle, v1.0.1, est datée de 2004.

Markdown désigne également le script de conversion de ce langage vers de l’HTML, Markdown.pl, initialement écrit en Perl 5.6.0 avant d’avoir été transcrit dans beaucoup d’autres langages (et notamment en module CPAN Text ::Markdown).

Le but de ce langage est la rédaction de documents pour le Web et l’intérêt de Markdown réside dans la lisibilité du texte non interprété, proche d’un E-mail au format texte, qui peut être utilisé tel quel ou converti en HTML valide. Le principe appliqué à Markdown est « facile à lire, facile à écrire ».

Influencée par d’autres langages tel que Setext, atx, Textile, reStructuredText, Grutatxt ou EtText, la plus grande inspiration de la syntaxe Markdown reste néanmoins la rédaction d’E-mails au format texte.

Exemples pratiques

Voici quelques exemples succincts de la syntaxe de base. La documentation officielle se trouve sur le site de Daring Fireball (http://daringfireball.net/projects/markdown/syntax) et des "cheat sheets" sont disponibles sur http://code.ahren.org/markdown-cheatsheet, http://scadahacker.com/library/Documents/Cheat_Sheets/HTML%20-%20Markdown.pdf et sur http://blog.lib.umn.edu/crosb002/leadership/Markdown_Cheat_Sheet.pdf. Les possibilités sont plus étoffées, ces extraits choisis sont représentatifs d’un texte simple.

Code

Pour commencer, le formatage permettant la mise en page des exemples ci-dessous.

Pour mettre du code dans une phrase (balise HTML <code>), il faut utiliser l’accent grave (`) autour du texte. Les paragraphes de codes sont identifiés à l’aide d’une indentation avant chaque ligne (soit 4 espaces ou une tabulation). Le texte contenu entre les balises <code> et n’est pas interprété par le parseur et rendu tel quel dans le fichier HTML.

Titres

Il existe plusieurs moyens d’écrire des titres <h1> et <h2> :

 Header 1
 ========
 Header 2
 --------

L’utilisation de # permet également de marquer le niveau du titre (et les # finaux sont optionnels) :

 # Header 1 #
 ## Header 2
 ### Header 3  ###

Accentuation

L’accentuation sur un mot, à l’aide de l’italique, peut se faire avec des *astérisques* ou des _underscores_. Pour du texte gras, on utilise des doubles **astérisques** ou doubles __underscores__. Italique et gras peuvent alors être combinés de la manière suivante : **astérisques et _underscores_**.

Listes

  1. Premier niveau d’une liste ordonnée

  2. Une autre entrée de la liste

    • Une sous-liste non ordonnée
  3. Troisième entrée de la liste ordonnée (la numérotation s’incrémente tant qu’une entrée commence par un chiffre)

    1. Une sous-liste ordonnée
  4. Encore une entrée de la liste principale

    du texte devant être aligné avec l’entrée parente.

  5. Concernant les listes non ordonnées

    • les astérisques *,
    • le symbole moins (tiret) -
    • et le symbole plus +

    fonctionnent de la même manière

Blockquotes

Markdown prévoit des blocs de citation. De manière similaire aux E-mails, il faut utiliser le symbole > avant chaque ligne. Le résultat est la transformation du paragraphe dans une balise HTML <blockquote>.

Liens

Mardown pourvoit deux manières de faire des liens, au fil du texte ou par référence. De la première manière, le lien sera stipulé directement là ou il sera affiché :
Ceci est [un exemple](http://exemple.com/ "Titre optionnel") de lien.

À l’inverse, un lien par référence sera écrit comme suit :
Ceci est [un exemple][id] de lien par référence.

Ensuite, et ce n’importe où dans le document, il est nécessaire de définir la référence du lien de la manière suivante :

[id] : http://exemple.com/  "Titre optionnel"

La seconde méthode est alors pratique si un lien apparait plusieurs fois dans le document, ou pour regrouper tous les liens d’une énumération.

Images

Bien qu’il soit assez difficile d’imaginer une syntaxe intuitive pour placer des images dans un document texte, Markdown propose toutefois une notation similaire à celle des liens.

 ![Alt texte](/lien/vers/img.jpg "Titre optionnel")

Ou, de manière similaire aux liens par références :

 ![Alt texte][img]

Puis la référence elle-même, ailleurs dans le document :

 ![img] : url/vers/image  "Titre optionnel"

Attention, aucun attribut concernant la taille de l’image ou son positionnement n’est prévu dans le langage Markdown. L’utilisation d’image reste relativement sommaire.

Tableaux

Markdown ne fournit pas une syntaxe ad hoc pour les tableaux. En cas de nécessité, il est possible d’utiliser directement du code HTML, mais de base aucune balise Markdown ne permet l’équivalent de <table> et consorts.

HTML

En cas de besoin il suffit d’insérer du code HTML dans le document Markdown. Les seules restrictions sont que les éléments de type blocs (<div>, <table>, <code>, <p>, etc.) doivent être séparés du contenu environnant par des lignes vierges, et que les balises de début et de fin de bloc ne doivent pas être indentées avec espaces ou des tabulations. Inversement, les éléments de type span peuvent être placés n’importe où dans un paragraphe Markdown.

Comparaison de syntaxe

Souvent comparé à BBCode (utilisé sur les forums), ou à la syntaxe de Wikipedia, le wikitexte, Markdown est objectivement plus lisible et plus simple à écrire (source) :

BBCode

 [size=150]Lightweight Markup Languages[/size]
 According to [b]Wikipedia[/b] :
 [quote]
 A [url=http://is.gd/gns]lightweight markup language[/url]
 is a markup language with a simple syntax, designed
 to be easy for a human to enter with a simple text
 editor, and easy to read in its raw form.
 [/quote]
 Some examples are :
 [list]
 [*]Markdown
 [*]Textile
 [*]BBCode
 [*]Wikipedia
 [/list]
 Markup should also extend to [i]code[/i] :
 [code]
 10 PRINT "I ROCK AT BASIC !"
 20 GOTO 10
 [/code]

Wikipedia

 ==Lightweight Markup Languages==
 According to ’’’Wikipedia’’’ :
 :A [1]
 is a markup language with a simple syntax, designed
 to be easy for a human to enter with a simple text
 editor, and easy to read in its raw form.
 Some examples are :
 * Markdown
 * Textile
 * BBCode
 * Wikipedia
 Markup should also extend to ’’code’’ :
  10 PRINT "I ROCK AT BASIC !"
  20 GOTO 10

Markdown

 Lightweight Markup Languages
 ============================
 According to **Wikipedia** :
 > A [lightweight markup language](http://is.gd/gns)
 is a markup language with a simple syntax, designed
 to be easy for a human to enter with a simple text
 editor, and easy to read in its raw form.
 Some examples are :
 * Markdown
 * Textile
 * BBCode
 * Wikipedia
 Markup should also extend to _code_ :
     10 PRINT "I ROCK AT BASIC !"
     20 GOTO 10

Les avantages

Lisibilité et simplicité sont les principaux avantages de Markdown. Des grands noms d’Internet (StackOverflow, GitHub, Reddit ou encore Tumblr) l’utilisent comme syntaxe d’édition. La simplicité et la popularité de l’interpréteur (parseur) fait qu’il est présent par défaut dans bon nombre d’outils, des paquets d’un système d’exploitation jusque dans les plug-ins d’un CMS, en passant par la coloration syntaxique des éditeurs.

Les inconvénients

Bien que tous s’accordent sur l’esprit et l’élégance de Markdown, certains trouvent que plusieurs fonctionnalités lui manquent. La syntaxe Markdown ne couvrant pas tous ces usages, des "flavors" sont apparues. Les plus connues sont sans doute GitHub, MultiMarkdown ou encore Markdown Extra. Par conséquent, on pourrait lui reprocher la diversité de ses forks ou le manque de suivi du projet depuis 2004.

Le bilan

Le fait que des flavors existent prouve la popularité de la syntaxe Markdown et la reconnaissance qui lui est faite au travers des différents projets l’implémentant. Cependant, par choix je suppose, Markdown n’a jamais voulu se développer dans une direction qui aurait pu limiter les applications de base et qui rendrait le parseur plus complexe. Les flavors offrent de bons compléments, notamment la mise en forme de codes avec coloration syntaxique, tableaux, notes en bas de page, mises en forme de formules mathématiques, citations ou encore notes bibliographies, mais à sa manière Markdown a su se contenter de sa fonctionnalité première : la mise en forme de documents simples (Read Me et autres documents .txt) et d’E-mails au format texte.

Éditeurs

Bien qu’un simple éditeur de texte soit suffisant pour créer un document Markdown, certains éditeurs permettent de modifier la source et d’avoir un œil sur le résultat interprété en HTML (live preview ou WYSIWYG). Cela évite de devoir faire la conversion du fichier avec Markdown.pl à chaque modification de la source et fournis un certain confort d’utilisation. On trouve ces logiciels pour toutes les plates-formes, mobiles comprises, mais seule une sélection de ceux disponibles en ligne est citée ici, chacun étant libre de choisir ensuite une application compatible avec sa plate-forme. Tous ces éditeurs ont des particularités, les voici en quelques mots :

  • Dillinger.io l’éditeur « web 2.0 » sous licence MIT avec numérotation des lignes, une multitude de thèmes, ainsi qu’importation et exportation sur Dropbox ou GitHub.

  • Hashify est doté de quelques boutons facilitant l’édition, mais il fonctionne plutôt comme un pastebin avec raccourcissement d’URL et génération de QR code.

  • InstantMark se différencie par un CSS raffiné et la possibilité d’en changer (et donc de personnaliser à sa guise l’aperçu de son texte).

  • JonCombe permet de choisir l’organisation de la fenêtre, partage horizontal ou vertical, etc.

  • Pandoc est certainement le convertisseur le plus complet. Il permet de convertir du texte Markdown, reStructuredText, textile, HTML, DocBook, ou LaTeX vers une multitude de formats, dont ceux d’entrée plus quelques autres dont HTML5, AsciiDoc ou encore MediaWiki. Pandoc est écrit en Haskell sous licence GPL et est disponible en tant qu’exécutable pour toutes les plates-formes, permettant alors également la conversion vers PDF.

  • Pioul est un éditeur minimaliste et astucieux, simple et efficace.

  • Showdown, bien que d’apparence simpliste, est le résultat du portage Javascript de Markdown.pl qu’un certain nombre de convertisseurs utilisent. Les sources de showdown.js sont disponibles sur https://github.com/coreyti/showdown (Licence BSD).

MD2HTML et inversement

Le processus inverse, la génération d’un texte Markdown à partir d’un fichier HTML, est possible avec différents éditeurs dont html2txt d’Aaron Swartz, Markdownify (PHP) et en ligne avec http://domchristie.github.com/to-markdown/ ou comme vu précédemment Pandoc.

Conclusion

Un texte balisé avec Markdown pourra aussi bien être utilisé tel quel que transformé en HTML. Markdown simplifie grandement l’édition en évitant un balisage conséquent et permet à l’utilisateur de se focaliser sur le contenu du fichier. Les possibilités de Markdown sont minimalistes, son usage est limité à des documents tels que notes, Read Me ou E-mails au format texte. Les documents plus complexes ne conviennent pas à Markdown car ils seraient difficilement lisibles sans être transformés en HTML et plus compliqués à écrire. Par conséquent Markdown tient sa promesse « facile à lire, facile à écrire ».

Pour plus d’informations


 
  Article du FI-EPFL 2013 sous licence CC BY-SA 3.0 /N. Borboën

Note sur l’article

Afin de démontrer la lisibilité de la syntaxe Markdown, l’article est volontairement publié dans le code-source Markdown et sans mise en page particulière. Si la lecture sous cette forme vous dérange, vous pouvez lire la version convertie en HTML sur le site du Flash Informatique. Néanmoins, c’est la simplicité de rédaction (comparé à du code HTML par exemple) et la lisibilité de la source qui sont remarquables avec Markdown...

[1] lightweight markup language



Cherchez ...

- dans tous les Flash informatique
(entre 1986 et 2001: seulement sur les titres et auteurs)
- par mot-clé

Avertissement

Cette page est un article d'une publication de l'EPFL.
Le contenu et certains liens ne sont peut-être plus d'actualité.

Responsabilité

Les articles n'engagent que leurs auteurs, sauf ceux qui concernent de façon évidente des prestations officielles (sous la responsabilité du DIT ou d'autres entités). Toute reproduction, même partielle, n'est autorisée qu'avec l'accord de la rédaction et des auteurs.


Archives sur clé USB

Le Flash informatique ne paraîtra plus. Le dernier numéro est daté de décembre 2013.

Taguage des articles

Depuis 2010, pour aider le lecteur, les articles sont taggués:
  •   tout public
    que vous soyiez utilisateur occasionnel du PC familial, ou bien simplement propriétaire d'un iPhone, lisez l'article marqué tout public, vous y apprendrez plein de choses qui vous permettront de mieux appréhender ces technologies qui envahissent votre quotidien
  •   public averti
    l'article parle de concepts techniques, mais à la portée de toute personne intéressée par les dessous des nouvelles technologies
  •   expert
    le sujet abordé n'intéresse que peu de lecteurs, mais ceux-là seront ravis d'approfondir un thème, d'en savoir plus sur un nouveau langage.