Le logo Markdown 
apparaît parfois également ainsi 
version 2014-12-16 - © Creative Commons BY-SA 4.0
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 (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 ☺
Markdown
Pandoc
Autres langages de balisage légers…
«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.
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 Puis un autre paragraphe… |
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 4Un 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…
Les styles de base sont définis par la syntaxe suivante :
<em>) sera bordée à gauche et à droite par le caractère _ ou *<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), 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. é, &) 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 normalParagraphe 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
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) :
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)
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 !
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 : 
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 :
URL_IMAGE, n’importe où dans le document, par : [imgId]: URL_IMAGE "titre optionnel"![texte alternatif][imgId]Le logo Markdown 
apparaît parfois également ainsi ![autre variante][imgMD]
[imgMD]: markdown2.png "Markdown"Le logo Markdown apparaît parfois également ainsi
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 !
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 ![Markdown] est super légère et concise !
[faculté enac]: <http://enac.epfl.ch> "Environnement naturel..."
[markdown]: markdown1.png 'Markdown'La faculté ENAC forme des ing. et architectes…
La syntaxe est super légère et concise !
Rappelons encore (ce qui est illustré dans l’exemple ci-dessus) que :
urlId, imgId) ne sont pas case-sensitive et peuvent contenir des espacesURL peut optionnellement être définie entre < >titre optionnel des liens et des images peut être défini entre guillemets, apostrophes ou parenthèsesPour 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 Suisse1291. 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écutifsmais ici espacés
comme plusieurs
paragraphes consécutifs
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…
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'exclamationNous 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
«Whereas markdown was originally designed with HTML generation in mind, pandoc is designed for multiple output formats. Thus, while pandoc allows the embedding of raw HTML, it discourages it, and provides other, non-HTMLish ways of representing important document elements like definition lists, tables, mathematics, and footnotes.» (John MacFarlane)
Markdown est donc une syntaxe, inspirée du courrier électronique en mode texte et des wikis, conçue dans l’esprit d’une grande facilité d’écriture et de lecture, mais essentiellement orientée vers la génération de pages HTML simples. Son auteur n’ayant jamais souhaité enrichir cette syntaxe (p.ex. implémentation de tableaux, listes de définitions, notes de bas de page…), cela a favorisé l’émergence de nombreuses extensions implémentées par différents convertisseurs alternatifs, le plus abouti et polyvalent étant aujourd’hui Pandoc.
Développé par John MacFarlane (Prof. de philosophie (!) à l’Université de Berkeley) dans ses temps de “procrastination structurée”, Pandoc est un outil distribué sous license GPL v2 de conversion de documents très polyvalent et supportant de nombreux formats (une véritable pierre de rosette du traitement de documents, voir cette figure) :
Le grand intérêt de Pandoc, en ce qui nous concerne ici, est que non seulement il gère le format Markdown mais qu’il en étend largement et intelligemment la syntaxe (sans l’alourdir), rendant possible l’utilisation de ce format léger pour élaborer et manipuler des documents riches, comme on va le voir dans le chapitre qui suit.
Tout ce qui a été dit précédemment concernant la syntaxe de base Markdown est valable pour le convertisseur Pandoc. On décrit ci-après les principales extensions apportées à la syntaxe Markdown par Pandoc. Pour une présentation exhaustive de celles-ci, passez la commande man pandoc_markdown sous Linux ou Mac OS X, ou voyez le “Pandoc User’s Guide” sous Windows.
Important : Pandoc utilise exclusivement l’encodage de caractères UTF-8 en entrée et sortie. Si vous obtenez des erreurs lors d’une conversion, le plus vraisemblable est que votre fichier Markdown d’entrée est encodé en ISO-8859-* (ISO-Latin). Commencez donc par le re-sauvegarder en UTF-8.
Pour faire un saut de ligne (<br /> en HTML) au sein d’un paragraphe, on peut utiliser le backslash \ immédiatement suivi du saut à la ligne, ce qui est bien plus lisible, dans un éditeur, que les 2 espaces de la syntaxe Markdown. En fait cela revient à “échapper” le caractère newline.
La Cigale, ayant chanté tout l'été, \
Se trouva fort dépourvue \
Quand la bise fut venue.
_Jean de la Fontaine_La Cigale, ayant chanté tout l’été,
Se trouva fort dépourvue
Quand la bise fut venue.
Jean de la Fontaine
Voyez aussi la technique du bloc de lignes.
En premier lieu Pandoc permet, au moyen des options -N et --toc présentées plus bas, de numéroter automatiquement les titres du document ainsi que collecter ceux-ci pour établir une table des matières avec liens hypertextes vers les chapitres.
Il est possible d’associer aux titres des attributs de type classes ou identifiants ainsi que des paires clé=valeur. On définit ces propriétés entre { } directement à la suite du titre (sur la même ligne) ainsi : ## Texte du titre { #myId .myClass attribut="valeur" }
S’agissant d’une conversion en HTML, l’identifiant #myId ajoute un id="myId" à la balise <h*> du titre, ce qui donne la possibilité de définir ailleurs dans le document un lien vers ce titre avec [lien]#myId (générant <a href="#myId">lien</a>).
Si l’on fait numéroter les titres avec l’option pandoc -N, on peut ajouter l’attribut tiret - ou la classe .unnumbered aux titres que l’on ne souhaite pas faire numéroter.
### Titre avec Id et non numéroté {.unnumbered #premTitre}
### Titre _stylé_ non numéroté {style="background: #eee;" -}
Lien vers le [premier](#premTitre) de ces 2 titresNotez finalement que Pandoc exige que chaque titre soit précédé d’une ligne vide, ce qui n’est pas obligatoire dans la syntaxe de base Markdown.
Pandoc implémente les styles supplémentaires suivants :
<del>) en le bordant à gauche et à droite par 2 caractères ~~^ ^ (les éventuels espaces devant être préfixés par \)~ ~ (les éventuels espaces devant être préfixés par \)Une ~~portion de texte~~ barrée ! \
2^10^ vaut 1024 \
La molécule de l'eau est H~2~OUne portion de texte barrée !
210 vaut 1024
La molécule de l’eau est H2O
Comme pour les titres (ci-dessus) et les blocs de code (ci-dessous), on peut associer des attributs aux codes inlines :
Du `code inline`{style="color: #b00;"} reformaté, ou \
syntaxiquement coloré `print("Hello world !")`{.python}Du code inline reformaté, ou
syntaxiquement coloré print("Hello world !")
Pour définir un bloc de code, au lieu de l’indenter comme l’exige la syntaxe de base Markdown, Pandoc offre aussi la possibilité de le délimiter en-dessus et en-dessous par une ligne composée de 3 ou davantage caractères tildes ~ ou accents graves `, le tout devant être précédé et suivi d’une ligne vide.
Comme pour les titres et le code inline, Pandoc permet d’attacher des attributs au bloc (classes et identifiants CSS), définis entre { } à la fin de la première ligne de tildes.
Des classes CSS prédéfinies permettent d’activer la coloration syntaxique (syntax highlighting) de rendu du code et même activer la numérotation des lignes du code. Voyez les langages supportés en frappant pandoc --version. Au lieu de ~~~~~~~ { .langage } on peut aussi utiliser la forme simplifiée ~~~~~~~ langage (sans accolades et point).
~~~~~~~ { .python .numberLines startFrom="10" }
#!/usr/bin/env python3
from time import localtime
heure = localtime().tm_hour
if heure < 17:
print("Bonjour !")
else:
print("Bonsoir !")
~~~~~~~Un bloc de lignes est en quelque sorte une variante du bloc de code. Il consiste en une suite de lignes commençant par le caractère barre verticale |. Le découpage en lignes ainsi que l’indentation y sont aussi respectés, mais en plus le formatage Markdown s’applique et les balises HTML sont interprétées.
| Séquence de lignes dans lesquelles l'indentation est
| respectée, le **formatage** Markdown appliqué, y.c.
| définition de `code`, usage <u>balises</u> HTMLcode, usage balises HTMLL’affichage HTML de formules est possible en les définissant sous forme d’expressions TeX Math (voir par exemple ce tutoriel) simplement entourées de caractères dollars $ $. Il ne doit pas y avoir d’espace directement après le premier $ ni directement avant le second $.
Il faudra générer le code HTML en utilisant l’une des options de conversion Tex Math de la commande Pandoc.
$a \cdot x^2 + b \cdot x + c = 0 \quad \Longrightarrow \quad
x = \frac {-b \pm \sqrt{b^2 - 4ac}}{2a}$\(a \cdot x^2 + b \cdot x + c = 0 \quad \Longrightarrow \quad x = \frac {-b \pm \sqrt{b^2 - 4ac}}{2a}\)
Une image définie en tant que paragraphe indépendant (c’est-à-dire non pas insérée “au fil du texte” dans un paragraphe) est traitée par Pandoc comme une figure, et le texte alternatif est automatiquement utilisé pour constituer la légende sous la figure.
La syntaxe  génère donc dans ce cas en HTML la structure suivante :
<div class="figure">
<img src="URL_IMAGE" title="titre optionnel" alt="texte alternatif" />
<p class="caption">texte alternatif</p>
</div>Exemple :
↲
↲
Les extensions apportées par Pandoc à la syntaxe Markdown dans le domaine des listes sont nombreuses et particulièrement bienvenues.
Pandoc apporte aux listes numérotées les améliorations suivantes :
() en lieu et place du point pour indiquer qu’il s’agit d’une liste numérotée# peut être utilisé comme substitut au numéro à partir du second élément de la liste11. Liste dont la numérotation démarre au numéro spécifié
#. Élément suivant, etc...
(A) Liste numérotée par des lettres majuscules
f) sous-liste
#) numérotée par des lettres minuscules
(D) Élément suivant (la lettre D est ici sans effet car
ce n'est pas le 1er élément de la liste !)
(#) Etc...
I) Liste numérotée par des chiffres romains majuscules
i. sous-liste
#. numérotée par des chiffres romains minuscules
#) Élément suivantSi un paragraphe doit réellement commencer par une lettre suivie d’une parenthèse fermée, pour que cela ne soit pas interprété comme le début d’une liste numérotée on peut préfixer la parenthèse par un backslash, par exemple : A\)
Le caractère @ peut être utilisé pour créer une liste numérotée de façon continue à travers tout le document (appelée par Pandoc numbered example list). Ce caractère peut être suivi d’un label afin de pouvoir se référer, ailleurs dans le document, à l’élément considéré de la liste.
Ce type de liste peut être vu comme une alternative aux notes de bas de page.
L'EPFL [voir @epfl] se situe... La faculté ENAC
[voir @enac] forme des ingénieurs et architectes...
(@epfl) École polytechnique fédérale de Lausanne
(@enac) Faculté Environnement naturel, Architectural
et Construit
Suite du document...
@. Continuation de la liste
@. Etc...L’EPFL [voir @epfl] se situe… La faculté ENAC [voir @enac] forme des ingénieurs et architectes…
Suite du document…
Les listes de définitions correspondent à la structure HTML suivante, un peu désuète bien que fort pratique :
Dans la syntaxe Pandoc, le terme doit tenir sur une seule ligne et peut être optionnellement suivi d’une ligne vide. Il doit être suivi d’une ou plusieurs définition(s), chacune débutant par le caractère double point : ou tilde ~. Ce caractère sera facultativement précédé d’1 ou 2 espaces mais obligatoirement suivi d’1 à 4 espaces ou de 1 tab.
[EPFL](http://www.epfl.ch)
:⟼École polytechnique fédérale de Lausanne
⟼Située à l'ouest de Lausanne...
**ENAC**
~ Faculté Environnement Naturel, Architectural et Construit
~ Elle comporte 4 instituts...
Elle offre 3 plans d'études...École polytechnique fédérale de Lausanne
Située à l’ouest de Lausanne…
Avec Pandoc (et contrairement à l’implémentation originale Markdown), ce qui suit le dernier élément d’une liste peut être considéré comme subordonné au dernier élément de la liste. Si cela ne correspond pas à ce que l’on souhaite, la solution consiste à intercaler un commentaire HTML <!-- --> (un peu une bizarrerie, mais suggérée par MacFarlane).
1. éléments...
#. de liste...
subordonné au 2e élément de la liste !
#. continuation de la liste !
Et ci-dessous modification de ce comportement :
1. éléments...
#. de liste...
<!-- -->
bloc de code indépendant !
#. nouvelle liste !de liste…
subordonné au 2e élément de la liste !
continuation de la liste !
Et ci-dessous modification de ce comportement :
bloc de code indépendant !On dispose de deux techniques de définition de notes de bas de pages : les notes par référence et les notes inlines. Quel que soit le type de note, l’ensemble des notes seront automatiquement numérotées par Pandoc de façon continue pour tout le document. Le texte de la note peut bien entendu faire l’objet d’un formatage Markdown, contenir des liens, etc…
S’agissant d’une conversion Pandoc en HTML (type de document où la notion de “page” n’existe pas), toutes les notes seront rassemblées par le template par défaut au bas de la page web, c’est-à-dire juste avant la balise </body>, dans une division <div class="footnotes"> débutant par un trait horizontal <hr /> et sous forme d’une liste numérotée.
Voyez aussi l’alternative aux notes de bas de page offerte par les listes numérotées référençables.
A) Les notes par référence sont définies en deux étapes :
la note proprement dite, selon la syntaxe suivante : [^noteId]: texte de la note
• les notes peuvent être définies n’importe où dans le document
• le label noteId est case-sensitive et ne peut pas contenir d’espace
• notez bien le caractère circonflexe ^ précédant directement le label noteId
• notez aussi le double point : suivant directement le crochet ]
au fil du texte (inline), on insère tout simplement la référence vers la note avec : [^noteId]
Notez que le label [^noteId] est uniquement utilisé pour corréler la référence de la note avec la note elle-même.
B) Les notes inlines seront saisies au fil du texte tout simplement selon la syntaxe suivante : ^[texte de la note]
Notez bien le caractère circonflexe ^ précédant directement le crochet [
Dans l’exemple ci-dessous, la note Markdown est définie par référence, et le terme Pandoc fait l’objet d’une note inline. Mais toutes deux sont automatiquement déportées au bas de la présente page web !
Markdown[^mdown] est une syntaxe légère d'écriture
de documents.
[^mdown]: Markdown:
<https://daringfireball.net/projects/markdown/>
Pandoc^[Pandoc: <https://pandoc.org/>]
est un convertisseur de documents...Markdown1 est une syntaxe légère d’écriture de documents.
Pandoc2 est un convertisseur de documents…
Pandoc comble, dans ce domaine, l’une des grandes lacunes de la syntaxe de base Markdown en offrant pas moins de 4 syntaxes de définition de tableaux. Les 3 premières nécessitent l’usage d’une police de caractères en chasse fixe (pour définir l’alignement…), ce qui n’est pas le cas de la 4ème.
Par défaut les tableaux produits par Pandoc sont calés sur la gauche de la page, les bordures ne sont pas visibles, et la légende est placée au-dessus du tableau. Vous pouvez par exemple changer cela avec les directives CSS suivantes :
table { margin: auto; } /* centre le tableau dans la page */
table, th, td { border-collapse: collapse; border: solid 1px #999; padding: 3px; } /* ajout bordures */
caption { caption-side: bottom; } /* déplace la légende en-dessous du tableau */La syntaxe de ce type de tableau est la suivante :
<caption>) : une ligne vide, puis une ligne commençant par le caractère double-point : suivi du texte de la légendeLe type d’alignement dans chaque colonne (à gauche, à droite, centré) est déterminé par la position du texte des en-têtes relativement aux groupes de tirets définis dans ligne suivante. Prenez garde que le texte des en-têtes ainsi que le contenu des cellules ne déborde pas à gauche ou à droite du groupe de tirets correspondants, faute de quoi le texte sera tronqué et placé dans 2 colonnes !
Aligné à gauche Aligné à droite Texte centré
------------------ ------------------ -----------------
abcdef 1234 xyz
: Légende du tableau...| Aligné à gauche | Aligné à droite | Texte centré |
|---|---|---|
| abcdef | 1234 | xyz |
Les cellules peuvent ici contenir du texte sur plusieurs lignes. La syntaxe est similaire aux tableaux simples, sauf que :
--------------------------------------------------------
Aligné à gauche Centré dans la colonne
------------------------- ----------------------------
Plusieurs lignes de Usage des styles Markdown:
texte dans la cellule ! **gras** _italique_,
<u>balises</u> HTML...
Insertion `de code` Mais hélas pas de listes !
--------------------------------------------------------
: Légende du tableau...| Aligné à gauche | Centré dans la colonne |
|---|---|
| Plusieurs lignes de texte dans la cellule ! | Usage des styles Markdown: gras italique, balises HTML… |
Insertion de code |
Mais hélas pas de listes ! |
L’avantage par rapport au tableau multiligne est ici de pouvoir définir des listes dans les cellules, mais l’alignement n’est pas supporté et la syntaxe est plus complexe et :
= sépare la définition des en-têtes du contenu (pouvant être omise pour un tableau sans en-têtes)| et +| doivent être soigneusement alignés pour que le texte ne soit pas découpé/dispersé dans plusieurs cellules+----------------------------+--------------+
| En-tête | etc... |
+============================+==============+
| Plusieurs lignes de texte | - liste |
| dans la même cellule, mais | - à puces |
| toujours aligné à gauche ! |
+---+---+
| Texte _formaté_, | #. liste |
| `code`, etc... | #. numérotée |
+---+---+
: Légende du tableau...| En-tête | etc… |
|---|---|
| Plusieurs lignes de texte dans la même cellule, mais toujours aligné à gauche ! |
|
Texte formaté, code, etc… |
|
Implémenté depuis Pandoc 1.10, la syntaxe de ce type de tableau est très naturelle et légère. Son seul inconvénient est de ne pas supporter des cellules contenant plusieurs lignes de texte. Le type d’alignement dans chaque colonne (à gauche, à droite, centré) est astucieusement défini dans la seconde ligne par la position du caractère double point : relativement aux tirets (donc beaucoup moins contraignant que de devoir aligner le texte sur les tirets comme dans les précédents types de tableaux, et n’obligeant ainsi pas d’éditer le code source avec une fonte en chasse fixe).
A des fins esthétiques, vous pouvez débuter et terminer chaque ligne par |, mais ce n’est pas obligatoire. Le nombre de tirets dans la seconde ligne n’est pas significatif.
Aligné à gauche | Aligné à droite | Texte centré | Défaut
:---|---:|:---:|---
abcdef | 1234 | xyz | etc
ghi jkl mno pqr | 567890 | ........ | etc
: Légende du tableau...| Aligné à gauche | Aligné à droite | Texte centré | Défaut |
|---|---|---|---|
| abcdef | 1234 | xyz | etc |
| ghi jkl mno pqr | 567890 | …….. | etc |
Au tout début du document (donc sans insérer de contenu ou de lignes vides avant !) il est possible de spécifier, au moyen de 3 lignes débutant par le caractère pour-cent % :
<title> de la page et le premier titre <h1>)<meta name="author" ...>)Si l’une ou l’autre de ces informations doit être omise, laissez le caractère % suivi d’une ligne vide. Si le titre ou la définition des auteurs nécessitent plusieurs lignes de texte, on peut faire usage de lignes supplémentaires pour autant qu’elles débutent par un espace.
La conversion Pandoc en HTML avec le template par défaut insérera, pour autant que l’option -s ou --standalone soit utilisée, juste après la balise <body> et avant l’éventuelle table des matières : le titre dans une structure <h1 class="title">, l’auteur dans une structure <h2 class="author">, et la date dans une structure <h3 class="date"> (éléments que vous pouvez donc styler par CSS).
Comme vous le voyez dans l’exemple ci-dessous, on peut faire usage du formatage Markdown (styles, liens…) dans ces éléments.
% Introduction à **Markdown** et **Pandoc**
% [Jean-Daniel Bonjour](https://www.jdbonjour.ch)
% rév. 12.4.2013
suite du document...Le code HTML inclus dans un fichier Markdown est passé tel quel par Pandoc dans le cas d’une conversion en HTML ou en slide shows HTML.
Lorsque l’on définit des blocs HTML (<div>, <table>…), Pandoc interprète la syntaxe Markdown à l’intérieur de ceux-ci, contrairement au convertisseur Markdown.pl original. A titre d’exemple, et pour des raisons de mise en page (placement côte à côte du code Markdown et de son rendu HTML), le présent document fait massivement usage de <div> HTML à l’intérieur desquelles nous utilisons la syntaxe Markdown.
Il y a deux exceptions à cela : le texte compris dans des blocs <script> ou <style> ne sera jamais interprété comme du Markdown… ce qui est finalement tout-à-fait logique !
Pandoc permet la gestion de citations et références bibliographiques dans de nombreux formats (BibTeX/bib, MODS, RIS, ISI/wos, MedLine, Copac, JSON, EndNote enl/xml…) et s’interface avec l’excellent logiciel libre Zotero. Si vous êtes intéressé par ces possibilités, voyez man pandoc sous Linux ou Mac OS X, ou le “Pandoc User’s Guide” sous Windows (au chapitre “Citations”).
Avec certaines options spécifiques de la commande pandoc présentées plus bas, il est très aisé de réaliser des slide shows HTML.
Le document Markdown sera découpé en slides selon les principes suivants :
----- produisant <hr /> en HTML) fait débuter un nouveau slide sans titrelevel_number (spécifié par l’option --slide-level) débute un nouveau slidelevel_number génère un sous-titre dans le slide courantlevel_number génère un slide de titre ne contenant que celui-ciLes métadonnées du document généreront la page de titre du slide show.
Pour styler les slide shows, voyez man pandoc sous Linux ou Mac OS X, ou le “Pandoc User’s Guide” sous Windows.
% Slide show Pandoc
% <https://www.jdbonjour.chl>
% 12.4.2013
# Premier slide
Liste à puce
* Pomme
- golden
- boskoop
* Poire
Liste numérotée
1. Chat
#. Chien
# Second slide
## Titre 2e niveau
Paragraphe de texte
## Autre titre 2e niveau
Ci-après saut manuel de slide
-----------------
**Slide sans titre**
Insertion d'image ou figure :
Voyez le résultat sous forme de slide show :
Il est en outre possible de faire des slide shows PDF basés LaTeX beamer.
L’objectif de ce document n’est pas de couvrir les fonctionnalités de Pandoc en relation avec TeX/LaTeX. Mais pour les personnes intéressées, sachez notamment que :
\newcommand et \renewcommandPour davantage d’informations à ce sujet, voyez man pandoc sous Linux ou Mac OS X, ou le “Pandoc User’s Guide” sous Windows.
Lorsque l’on exécute pandoc avec l’option -s (ou --standalone), Pandoc incorpore au fichier de sortie diverses informations (p.ex. le bloc <head>...</head> pour une conversion en HTML) structurées selon le template par défaut correspondant au format de sortie. L’utilisateur peut cependant élaborer et fournir son propre fichier template avec l’option --template=fichier
Le template par défaut relatif à un format donné peut être visualisé avec la commande : pandoc -D format. Nous vous laissons examiner celui correspondant au format de sortie HTML en passant la commande pandoc -D html. Vous y verrez tout le code HTML inclus par l’option -s, ainsi que des directives et variables entourées de caractères $ $. Certaines de ces variables sont prédéfinies par Pandoc, telles que : $toc$ (code généré de la table des matières), $body$ (code proprement dit résultant de la conversion Pandoc)…
En créant votre propre fichier template, il vous sera possible de définir vos propres variables et injecter ainsi du contenu aux emplacements correspondants dans le fichier de sortie en passant les valeurs de ces variables avec l’option pandoc -V variable=valeur. A titre d’exemple, voyez cette page qui indique comment vous pourriez ajouter un titre au-dessus de la table des matières.
Pour en savoir plus sur ce mécanisme (notamment sur la signification des variables prédéfinies ainsi que l’usage des directives if et for), voyez man pandoc sous Linux ou Mac OS X, ou le “Pandoc User’s Guide” sous Windows.
Il existe de nombreux outils liées à Pandoc (voir cette page). Mentionnons en particulier :
Les explications originales relatives à l’installation de Pandoc sont accessibles sur le site Pandoc.
La méthode la plus simple consiste à installer la version de Pandoc packagée dans le dépôt officiel de votre distribution Linux. Sous Debian et dérivés ainsi que Fedora, il s’agit du package nommé pandoc que l’on installe donc de façon habituelle avec : sudo apt-get install pandoc (Debian/Ubuntu) ou yum install pandoc (Fedora). On obtiendra cependant ainsi des versions de Pandoc anciennes dans lesquelles nombre de possibilités présentées ci-dessus ne sont pas encore implémentées.
Pandoc évoluant très rapidement, si vous souhaitez bénéficier des dernières évolutions de ce convertisseur (et dernières extensions apportées à Markdown !), étant donné qu’il n’existe actuellement sous Ubuntu pas de PPA (dépôt alternatif de paquets logiciels) relatif à Pandoc, il s’agit donc de l’installer/compiler soi-même en procédant ainsi :
sudo apt-get install haskell-platform (une soixantaine de packages seront installés occupant ~500 MB)cabal update && cabal install pandoc (ne prenez pas garde aux messages d’avertissement) ; cette commande pourra être ultérieurement répétée pour bénéficier des mises à jour de Pandoc~/.cabal (arborescence standalone qui pourrait être copiée sur une autre machine), l’exécutable étant ~/.cabal/bin/pandocPATH en conséquence (en introduisant p.ex. la ligne export PATH="$HOME/.cabal/bin:$PATH" au bas de votre prologue ~/.profile)La procédure est similaire sous Fedora.
Téléchargez l’installeur pandoc-<version>-windows.msi depuis ce lien, et exécutez-le avec des droits d’administration. L’installation s’effectue automatiquement dans le compte de l’utilisateur courant (dossier C:\Users\<username>\AppData\Local\Pandoc). La variable PATH de l’utilisateur est complétée de façon que la commande pandoc soit accessible depuis n’importe quel répertoire (dans une fenêtre “Invite de commande”). Finalement le menu Démarrer de l’utilisateur est complété par un raccourci vers le “Pandoc User’s Guide”.
Téléchargez l’installeur pandoc-<version>-osx.pkg depuis ce lien, exécutez-le et suivez les indications.
Pour être en mesure de faire une conversion directe Markdown → PDF, Pandoc nécessite qu’un environnement LaTeX soit présent sur votre machine, par exemple :
texlive-latex-recommended(plus de 200 MB) outexlive-base (48 MB)Une alternative, présentée plus bas, consiste à effectuer une conversion Markdown → HTML avec Pandoc, puis HTML → PDF avec un autre outil.
Pandoc est un outil qui s’utilise en ligne de commande, donc a priori plutôt dans une fenêtre terminal ! Si cela ne vous convient pas, nous vous indiquons au chapitre Éditeurs comment définir les commandes de conversion utiles dans l’éditeur.
Comme vu plus haut, souvenez-vous que Pandoc travaille exclusivement avec l’encodage de caractères UTF-8.
La forme générale de la commande Pandoc est la suivante : pandoc option(s) fichier(s)_entree ou pandoc option(s) URL. Voici quelques exemples :
pandoc -o sortie.out entree1.in entree2.inentree1.in entree2.in dans le fichier sortie.out. Le format d’entrée est automatiquement déduit de l’extension .in des fichiers d’entrée (p.ex. .md ⇒ Markdown/Pandoc), et le format de sortie de l’extension .out du fichier de sortie (p.ex. .html ⇒ HTML). Il n’y a pas d’extension spécifique relative au format Markdown/Pandoc étendu.
pandoc -f html -t markdown urlurl spécifiée, et envoie le résultat sur la sortie standard.
pandoc -o sortie.odt entree.mdentree.md en un fichier sortie.odt au format ODF (LibreOffice Writer).
Parmi les très nombreuses options de la commande Pandoc, nous ne présentons ci-après que celles qui nous semblent les plus utiles pour un usage courant. Sachez que :
pandoc -h et pandoc --helpman pandoc sous Linux ou Mac OS X, ou dans le “Pandoc User’s Guide” sous Windows-o fichier.extformat à partir de l’extension ext spécifiée. Sans cette option, le résultat de la conversion est envoyé sur la sortie standard.
-f format ou --from format ou -r format ou --read formatformat d’entrée (prime sur le format dérivé de l’extension du fichier d’entrée)
-t format ou --to format ou -w format ou --write formatformat de sortie (prime sur le format dérivé de l’extension du fichier de sortie)
Tous les formats d’entrée et sortie supportés sont indiqués par la commande pandoc -h, ou par man pandoc sous les options -f et -t. Le format markdown désigne le Pandoc extended Markdown, et markdown_strict utiliserait l’original unextended markdown (ignorant les extensions Pandoc).
-s ou --standalonepandoc -D html) ajoute donc notamment le bloc <html><head>...</head> ainsi que les balises <body> et </body></html>. L’option --template=fichier permettrait d’utiliser son propre fichier de template.
-c fichier.css ou --css=fichier.cssfichier.css au fichier HTML généré
-H header.html -B body.html -A footer.htmlInsère respectivement :
header.html (p.ex. du CSS, JavaScript…) juste avant la balise </head>body.html juste après la balise <body>footer.html juste avant la balise </body>Le fait d’utiliser l’une ou l’autre de ces options active implicitement l’option -s
--ascii& pour &)
-S (S majuscule) ou --smart--self-contained<img src="data: ..." />, les feuilles de style avec <link href="data:text/css,..." type="text/css" />, les scripts JavaScript, etc… Très utile pour les slide shows !
Les formules TeX Math (voir exemple plus haut) sont converties en MathML pour être affichées dans les navigateurs web supportant ce standard du W3C. On utilise pour cela l’une des options de conversion suivantes :
-s --mathml-s --mathjax-s --jsmath=script.jsscript.js
-N ou --number-sections<h*>. Utiliser l’option --number-offset=numero(s) pour faire débuter la numérotation au(x) numero(s) +1 spécifié(s)
--toc ou --table-of-contentslevels spécifié par l’option supplémentaire --toc-depth=levels. En l’absence de cette option, seuls les titres des 3 premiers niveaux sont collectés (en HTML: <h1>, <h2>, <h3>). Dans le cas d’une conversion en HTML, la table des matières est placée juste après la balise <body>. Cette option n’a pas d’effet si l’on produit des docbooks ou des slide shows.
La conversion Markdown → PDF directe par Pandoc nécessite de disposer d’un environnement LaTeX sur sa machine. Une manière alternative de procéder consiste à effectuer, en 2 étapes :
wkhtmltopdfS’agissant de wkhtmltopdf (outil basé sur le moteur de rendu WebKit), vous trouvez sous ce lien les installeurs pour tous les OS (le plus simple sous Ubuntu consistant à installer le package wkhtmltopdf). La conversion HTML → PDF s’effectue ensuite à l’aide de la commande : wkhtmltopdf fichier.html fichier.pdf. Des options de conversions sont disponibles (documentées sous man wkhtmltopdf et wkhtmltopdf --extended-help).
--reference-odt=fichierfichier ODT spécifié comme référence de styles pour la production d’un fichier ODT
--css=fichierfichier CSS spécifié comme référence de styles pour la production d’un fichier ePub.
Les options ci-après sont spécifiques à la production de slide shows aux formats HTML (S5, Slidy, Slideous, DZSlides, Revealjs) ou PDF (LaTeX beamer). Voyez le résultat avec notre exemple ci-dessus.
Options générales
--slide-level=level_number-i ou --incremental> (générant <blockquote> en HTML).
Spécification du slide engine
-s -t s5 -i --slide-level=level_number --self-contained--self-contained le fichier HTML est totalement standalone (incorporation des données liées telles que les images…) ; il faut sinon disposer, dans le dossier courant, d’un dossier s5/default contenant divers fichiers (slides.js, *.css, *.gif) à télécharger depuis ce lien.
Usage du clavier et de la souris :
Ø d’affichage de tous les slides en mode texte, et le menu de sélectionnement de slides-s -t slidy -i --slide-level=level_number --self-contained--self-contained le fichier HTML est totalement standalone (incorporation des données liées telles que les images…) ; il fait sinon usage d’un JavaScript et d’un CSS en ligne via Internet.
Usage du clavier et de la souris :
-s -t slideous --slide-level=level_number --self-contained--self-contained le fichier HTML est totalement standalone (incorporation des données liées telles que les images…).
Usage du clavier et de la souris :
-s -t dzslides -i --slide-level=level_number --self-contained--self-contained, le code JavaScript et CSS nécessaire. L’option --self-contained reste cependant utile pour produire un fichier HTML totalement standalone (incorporation des données liées telles que les images…) !
Usage du clavier et de la souris :
-s -t revealjs -i --slide-level=level_number --self-contained-t beamerPour faciliter la rédaction et le confort de la lecture, vous avez tout intérêt à utiliser un éditeur de texte supportant la coloration syntaxique Markdown (syntax highlighting). Parmi les éditeurs libres ou gratuits, nous pouvons vous suggérer :
Sous Geany
On peut par exemple définir les commandes spécifiques suivantes sous Build > Set Build Commands :
commande par exemple nommée “Markdown to HTML” effectuant :
pandoc -s -N --toc -c "%e".css -o "%e".html "%f"
et que l’on pourra alors utiliser avec Build > Markdown to HTML (ou raccourci <F8>)
commande par exemple nommée “HTML to PDF” effectuant :
wkhtmltopdf "%e".html "%e".pdf (présuppose l’installation du package wkhtmltopdf)
et que l’on pourra alors utiliser avec Build > HTML to PDF (ou raccourci <F9>)
Pour modifier éventuellement les raccourcis de ces commandes, aller sous Edit>Preferences, onglet “Keybindings”, puis changer respectivement les raccourcis Build>Compile (c’est celui de MD to HTML) et Build>Build (celui de HTML to PDF).
Notez qu’un plugin spécifique Markdown permettrait sous Geany de faire de l’édition de code Markdown dans une fenêtre tout en ayant le rendu HTML en temps réel dans une autre fenêtre.
Sous Gedit
Il faut en premier lieu activer le plugin “External Tools” sous Edit>Preferences, dans l’onglet “Plugins”. On peut ensuite par exemple définir les commandes spécifiques suivantes sous Tools>Manage External Tools, avec le bouton [+] :
<F2> #!/bin/sh
NOM_DOC=`echo $GEDIT_CURRENT_DOCUMENT_NAME | sed "s/\..*$//"`
pandoc -s -N --toc -c "%e".css -o "$NOM_DOC".html "$GEDIT_CURRENT_DOCUMENT_NAME"<F3>wkhtmltopdf) #!/bin/sh
NOM_DOC=`echo $GEDIT_CURRENT_DOCUMENT_NAME | sed "s/\..*$//"`
wkhtmltopdf "$NOM_DOC".html "$NOM_DOC".pdf
Jean-Daniel Bonjour, 2013-2014
Pandoc: https://pandoc.org/↩