YannStatic

Élaboration et conversion de documents avec Markdown

  •   6 mai   2019
Afficher/cacher Sommaire

Introduction

Élaboration et conversion de documents avec Markdown et Pandoc par Jean-Daniel Bonjour, EPFL-ENAC-IT, © Creative Commons BY-SA (révision 16.12.2014)

Avant-propos

Cette page web décrit le langage de balisage léger d’écriture de documents Markdown (markup language) ainsi que l’utilisation du convertisseur Pandoc, notamment les très nombreuses, riches et utiles extensions apportées à la syntaxe Markdown par ce convertisseur.

Cette page a été elle-même rédigée en langage Markdown (vous pouvez examiner son code source) en faisant un large usage des extensions offertes par Pandoc (dont il faut utiliser une version ≥ 1.11.1). Elle a été convertie en HTML avec la commande pandoc -s -N --toc --mathjax -c markdown-pandoc.css -o index.html index.md. Son rendu web s’appuie en outre sur une feuille de style CSS spécifique que nous avons réalisée et qui est plutôt orientée impression.

Vous pouvez aussi télécharger la [version e-book](index.epub) (au format ePub) de ce document, à consulter par exemple avec l’excellente liseuse libre Calibre.

Une dernière remarque : ne soyez pas effrayé par le volume de cette documentation ! À l’usage, vous constaterez que les concepts présentés ici sont finalement extrêmement naturels, et que Markdown et Pandoc sont très faciles à mettre en oeuvre ☺

Quelques références

Markdown

Pandoc

Autres langages de balisage légers…

Le langage Markdown

Généralités

«A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.» (John Gruber)

Markdown est une syntaxe légère d’écriture de documents définie en 2004 par John Gruber avec la collaboration de Aaron Swartz. Elle a été conçue pour être aussi facile à lire et à écrire que possible. D’importants outils (IPython Notebook…) et de nombreux sites Internet (GitHub, StackExchange, Reddit, Tumblr…) l’utilisent comme syntaxe d’édition. Mais en raison du caractère non formel de la définition originale de cette syntaxe par Gruber, de certaines ambiguïtés et du besoin d’évolution de ce format, un projet de standardisation débute en 2014 sous la dénomination CommonMark.

Bien que cette syntaxe permette la conversion en différents formats de documents, elle est principalement orientée vers la production de documents (X)HTML simples, raison pour laquelle nous indiquerons souvent dans ce document les balises (X)HTML résultant de la conversion Markdown dans ce format.

Syntaxe de base du langage Markdown

Paragraphes, sauts de ligne

Dans la syntaxe Markdown, un paragraphe (<p>...</p> en HTML) est constitué d’une ligne ou de plusieurs lignes consécutives. Le passage au paragraphe suivant s’effectue en introduisant une ou plusieurs lignes vides.

Pour effectuer un saut de ligne à l’intérieur d’un paragraphe (<br /> en HTML), il faut introduire 2 ou davantage de caractères espaces à la fin de la ligne (avant le saut à la ligne).

Voici un paragraphe↲
de texte avec⎕⎕↲   
un saut de ligne.↲  
↲  
Puis un autre paragraphe...

Voici un paragraphe de texte avec
un saut de ligne.

Puis un autre paragraphe…

Titres

Un titre consiste en un paragraphe débutant par 1 à 6 caractères dièses # suivi(s) de l’intitulé proprement dit du titre. Le nombre de # débutant la ligne spécifie le niveau du titre : par exemple ### Titre... est un titre de 3e niveau (<h3>Titre...</h3>). On peut facultativement terminer la ligne de titre par des dièses # (peu importe leur nombre).

Une autre syntaxe peut être utilisée pour les titres de premier et second niveau. Pour le 1er niveau (<h1>), on peut saisir le texte du Titre directement suivi d’une ligne composée d’un ou plusieurs caractères égal = puis d’une ligne vide. Pour le 2ème niveau (<h2>), le titre sera suivi d’une ligne composée d’un ou plusieurs tirets -

Notez finalement que l’on peut faire usage de styles et liens (techniques présentées plus bas) à l’intérieur des titres.


	# Titre de niveau 1
	
	Autre syntaxe pour niveau 1
	===========================
	
	## Titre de niveau 2
	
	Syntaxe ⎯alternative⎯ pour niveau 2
	-----------------------------------
	
	### Titre de niveau 3 incluant [un lien](#)
	
	#### Titre de niveau 4

Titre de niveau 3 incluant un lien

Traits horizontaux

Un trait horizontal (<hr />) est défini par un nouveau paragraphe (donc précédé et suivi d’1 ligne vide au moins) comportant au minimum 3 caractères de type tiret -, souligné _ ou étoile *, optionnellement séparés par des espaces.

	------------
	
	Paragraphe...
	
	*********
	
	Paragraphe...
	
	* * *

Paragraphe…

Paragraphe…

Styles et blocs

Les styles de base sont définis par la syntaxe suivante :

  • une portion de texte en italique (<em>) sera bordée à gauche et à droite par le caractère _ ou *
  • le texte en gras (<strong>) sera bordé à gauche et à droite par 2 caractères ** ou __

Pour insérer du code inline (<code>...</code> ⇒ texte en chasse fixe), on placera celui-ci entre ` ` (accents graves,AltGr 7), et ceux-ci seront doublés si ce code contient lui-même un ou plusieurs accents graves. Dans ce code inline, les directives de formatage Markdown _ * ainsi que les balises HTML ne sont pas interprétées mais restituées telles quelles.

	Mots en ⎯italique **gras**⎯ ou en **gras ⎯italique⎯**,
	du `code contenant des
	*balises* HTML, p.ex. <u> <span>` ...
	
	Mais _ ceci _ ou ** cela ** ne va pas (en raison d'espaces) !

Mots en italique gras ou en gras italique, du code contenant des *balises*, p.ex. <u> <span> …
Mais _ ceci _ ou ** cela ** ne va pas (en raison d’espaces) !

Pour définir un bloc de code (structure <pre>...</pre> en HTML), on fera précéder chaque ligne de 1 ou plusieurs tab ou de 4 espaces ou plus.
Notez que dès le 2ème tab ou le 5ème espace, ces caractères participent à l’indentation du code !
Dans un tel bloc, les directives de formatage Markdown _ *, les balises HTML ainsi que les caractères HTML (p.ex. &eacute;, &amp;) ne sont pas non plus interprétées (les caractères < > & étant affichés tels quels).

	 ⟼ Sur le pont d'Avignon
	 ⟼ ⎕⎕L'on y danse, l'on y danse,
	 ⟼ Sur le pont d'Avignon
	 ⟼ ⎕⎕L'on y danse tous en rond.

Sur le pont d'Avignon
  L'on y danse, l'on y danse,
Sur le pont d'Avignon
  L'on y danse tous en rond.

Pour décaler à droite un paragraphe (on appelle ça un bloc de “citation”, hérité de l’email), on fera précéder la première ligne du paragraphe (facultativement les suivantes) par le caractère >. En HTML cela générera un bloc <blockquote>. On peut faire des citations/décalages de 2ème niveau avec >> ou > >, de 3ème niveau avec >>> ou > > >, et ainsi de suite.

Rien n’interdit de faire usage de toute autre possibilité Markdown dans les citations (styles Markdown, titres, listes, blocs de code, ainsi que balises HTML…).


	Paragraphe normal

	> Début du bloc de citation
	>
	> * élément de liste
	> * second élément
	>
	>> Décalage de 2ème niveau, usage de _styles_
	Markdown, <u>balises</u> HTML
	>
	> ⟼ Bloc de code dans la citation

	Retour à l'alignement normal

Paragraphe normal

Début du bloc de citation

  • élément de liste
  • second élément

Décalage de 2ème niveau, usage de styles Markdown, balises HTML

  Bloc de code dans la citation

Retour à l’alignement normal

Liens

Markdown propose deux techniques de définition de liens.

A) Pour définir un lien inline (technique HTML classique du lien “au fil du texte”) :

  • si l’URL est ancrée à un texte, on utilise la syntaxe : [texte](URL "titre optionnel")
    • notez bien l’usage respectif des crochets et parenthèses, ainsi que l’absence d’espace entre ] et (
    • le titre optionnel est le texte qui s’affichera lorsque le curseur survole le lien
    • le texte d’ancrage peut bien entendu faire l’objet d’un formatage Markdown (p.ex. gras, italique…)

  • si l’on veut insérer au fil du paragraphe une URL (non ancrée à un texte, mais présentée telle quelle et cliquable), on utilise simplement la syntaxe : <URL> (donc entre signes < et >)
    • pour définir des adresses emails cliquables, il n’est pas nécessaire de les préfixer par mailto:

	Lien externe : l' [EPFL](http://www.epfl.ch "École polytechnique fédérale de Lausanne") se trouve...  
	Web: <http://www.epfl.ch>, Email: <accueil@epfl.ch>
	
	Lien interne : vers le [haut de la page](#)

Lien externe : l’ EPFL se trouve…
Web : http://www.epfl.ch, Email: accueil@epfl.ch

Lien interne : vers le haut de la page

Remarque : si vous examinez le code HTML, vous constaterez que les liens de type <adresse_email> sont automatiquement encodés (et même associés par Pandoc à du JavaScript) et sont de ce fait relativement résistant aux robots de spam !

B) Markdown offre en outre la possibilité très intéressante de définir des liens par référence, explicite ou implicite. On réalise cela en deux étapes (ci-dessous la référenciation explicite) :

  1. d’une part on définit, n’importe où dans le fichier, l’URL et un label urlId permettant de s’y référer selon la syntaxe : [urlId]: URL "titre optionnel"
    • notez bien le double point : suivant directement le crochet ]
    • l’URL peut optionnellement être écrite entre < >
    • sachez aussi que le label urlId n’est pas case-sensitive et peut contenir des espaces !
    • ces 3 champs peuvent optionnellement être définis sur 2-3 lignes (mais sans intercaler de ligne vide)

  2. au fil du texte (inline), on ancre simplement par référence cette URL à un texte avec : [texte][urlId]
    • notez bien que l’on n’utilise ici que des crochets, ainsi que l’absence d’espace entre ] et [

	La [faculté **ENAC**][webEnac] forme des ing. et architectes...  
	L'[ENAC][webEnac] est constituée de...

	[webEnac]: http://enac.epfl.ch "Environnement naturel..."

La faculté ENAC forme des ing. et architectes…
L’ENAC est constituée de…

Le grand intérêt de cette seconde technique de “liens par référence” est de pouvoir déporter les URLs en dehors du texte proprement dit (allégeant la composition et la lecture de celui-ci), d’éventuellement regrouper toutes les URLs au même endroit dans le fichier, et surtout de pouvoir partager la même URL par plusieurs liens en ne la définissant qu’une fois dans le document !

Images inlines

Syntaxiquement, un lien Markdown précédé du caractère point d’exclamation ! est considéré comme une image. De la même façon que pour les liens, il existe deux syntaxes d’insertion d’images au fil du texte.

A) L’insertion d’image par référence inline s’effectue selon la syntaxe : ![texte alternatif](URL_IMAGE "titre optionnel")
Notez donc bien le point d’exclamation débutant cette expression. Le titre optionnel est le texte s’affichant lorsque le curseur survole le lien. Quant au texte alternatif, c’est celui qui apparaît lorsque le navigateur ne prend pas en charge l’affichage des images.

B) Par ailleurs, et comme pour les liens, on peut également insérer une image par référence en deux étapes avec :

  1. d’une part la définition de l’URL_IMAGE, n’importe où dans le document, par : [imgId]: URL_IMAGE "titre optionnel"
    (optionnellement définis sur 2-3 lignes, mais sans intercaler de ligne vide)
  2. d’autre part l’insertion proprement dite, au fil du texte, de l’image référencée avec : ![texte alternatif][imgId]
	Le logo Markdown ![logo Markdown](markdown-logo.png "Markdown")
	apparaît parfois également ainsi ![autre variante][imgMD]

	[imgMD]: /images/markdown-logo.png "Markdown"

Le logo Markdown logo Markdown apparaît parfois également ainsi autre variante

Le grand intérêt de cette seconde technique réside notamment dans la possibilité d’insérer de façon très concise la même image (icône, logo…) à plusieurs endroits dans le document !

Définition de liens ou d’images par référence implicite

Lorsque l’on insère par référence, dans un paragraphe, un lien ou une image définis ailleurs dans le document, il est possible d’omettre le second champ [urlId] ou [imgId] ! On parle dans ce cas de référence implicite, car cela revient à établir un lien vers une référence de nom identique à ce qui est défini dans le premier champ : ainsi [du texte] renverrait vers la référence [du texte]: url. Cette syntaxe apporte une concision extrême dans l’utilisation de liens et d’images !

	La [faculté ENAC] forme des ing. et architectes...
	
	La syntaxe ![image] est super légère et concise !

	[faculté enac]: <http://enac.epfl.ch> "Environnement naturel..."
	[image]: /images/markdown-logo.png 'Markdown'

La faculté ENAC forme des ing. et architectes…

La syntaxe image est super légère et concise !

Rappelons encore (ce qui est illustré dans l’exemple ci-dessus) que :

  • les labels (urlId, imgId) ne sont pas case-sensitive et peuvent contenir des espaces
  • dans les définition de références, l’URL peut optionnellement être définie entre < >
  • le titre optionnel des liens et des images peut être défini entre guillemets, apostrophes ou parenthèses

!!!ATTENTION , référence implicite problème avec les images pour des éditeurs avec aperçu (retext)

Listes

Pour définir une liste numérotée (<ol>), il suffit de saisir, au début de chaque élément de la liste, un nombre quelconque suivi d’un point et de 1 ou plusieurs espaces ou tab. Si un paragraphe doit commencer par un nombre, il faut préfixer le point du nombre par \ afin qu’il ne soit pas considéré comme un début de liste numérotée.

Pour définir une liste à puce (<ul>), il suffit de débuter chaque item par l’un des caractères *, + ou - suivi d’1 ou plusieurs espaces ou tab.

Le début et la fin de la liste doivent être respectivement précédé et suivi d’1 ligne vide au moins.

Il est possible de faire des listes imbriquées : pour cela la sous-liste devra être indentée à droite d’1 tab ou de 4 espaces par rapport à l’élément supérieur. Les sous-listes n’ont pas besoin d’être précédées et suivies d’une ligne vide.

	1. raisin
	0. pomme
	 ⟼ * golden
	 ⟼ - granny smith
	 ⟼ + boskoop
	0. abricot
	
	1291\. Signature du pacte fédéral Suisse
  1. raisin
  2. pomme
    • golden
    • granny smith
    • boskoop
  3. abricot

1291. Signature du pacte fédéral Suisse

Si l’on désire un espacement de paragraphe entre les éléments de la liste, on définira ceux-ci comme des paragraphes c’est-à-dire en intercalant des lignes vides.

	* les éléments
	* sont ici
	* serrés

    ---

	1. mais ici espacés
	↲
	0. comme plusieurs
	↲
	0. paragraphes consécutifs
  • les éléments
  • sont ici
  • serrés

  1. mais ici espacés

  2. comme plusieurs

  3. paragraphes consécutifs

Inclusion de code HTML dans un fichier Markdown

La plupart des balises HTML (y compris <span>) peuvent être utilisées dans des paragraphes Markdown.

Les structures HTML de type bloc (<div>, <table>, <pre>…) doivent cependant être précédées et suivies d’1 ligne vide au moins, et les balises de début et fin du bloc ne doivent pas être indentées (donc non précédées d’espaces ou tab). Mais attention : sachez qu’avec la syntaxe stricte Markdown (cette restriction ne s’applique pas à Pandoc) le formatage Markdown n’est pas appliqué à l’intérieur de tels blocs HTML !

	Utilisation de balises HTML : <u>souligné</u>,
	  <span style="color: #f00;">couleur</span> ...

	<table border="1" cellspacing="0" cellpadding="4" align="center">
	   <tr> <td>Tableau</td> <td>par balises HTML</td> </tr> 
	</table>
	
	Paragraphe _normal_...

Utilisation de balises HTML : souligné, couleur …

Tableau par balises HTML

Paragraphe normal…

Échappement de certains caractères

A l’extérieur des structures de type code inline ou bloc de code, si l’on veut afficher les caractères ci-dessous (qui ont sinon une signification Markdown ou Pandoc) il peut être nécessaire de les “échapper” en les préfixant par le caractère backslash \


		\       backslash
		`       accent grave
		*       étoile/astérisque
		⎯       souligné
		+       plus
		-       tiret/moins
		(  )    parenthèses
		[  ]    parenthèses carrées
		{  }    accolades
		<  >    crochets pointus (de balises)
		#       dièse
		@       arobase
		~       tilde
		.       point
		!       point d'exclamation

Installation et utilisation du convertisseur Markdown original

Nous vous recommandons plutôt d’utiliser le convertisseur Pandoc qui offre bien plus de possibilités. Si vous tenez cependant à tester le convertisseur Markdown original, sachez qu’il s’agit d’un simple script Perl sous license BSD téléchargeable via un lien au haut de la home-page du site Markdown. Il est donc nécessaire de disposer d’un interpréteur Perl sur votre machine (ce qui est par défaut le cas sous Linux et Mac OS X, mais pas sous Windows où vous pouvez utiliser le Strawberry Perl ou l’ActivePerl). La conversion d’un fichier Markdown en HTML s’effectue alors avec la commande : perl Markdown.pl fichier.md > fichier.html

Recherche