1 Introduction

1.1 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 riches et très utiles extensions apportées à la syntaxe Markdown par ce convertisseur.

Cette page a été rédigée en langage Markdown (vous pouvez examiner son code source) en faisant un large usage des extensions offertes par Pandoc (dont nous utilisons la version 1.11.1 du 17-03-2013). 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 la taille 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 faciles à mettre en oeuvre ☺

1.2 Quelques références

Markdown

Pandoc

Autres langages de balisage légers...

2 Le langage Markdown

2.1 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 sites Internet (GitHub, Reddit, StackOverflow, Tumblr...) l'utilisent comme syntaxe d'édition.

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.

2.2 Syntaxe de base du langage Markdown

2.2.1 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...

2.2.2 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 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

2.2.3 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...


2.2.4 Styles et blocs

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

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. &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

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

Bloc de code dans la citation

Retour à l'alignement normal

2.2.5 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") :

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:

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 !

2.2.6 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](markdown1.png "Markdown")
apparaît parfois également ainsi ![autre variante][imgMD]

[imgMD]: markdown2.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 !

2.2.7 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 ![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 Markdown est super légère et concise !

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

2.2.8 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
  1. mais ici espacés

  2. comme plusieurs

  3. paragraphes consécutifs

2.2.9 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...

2.2.10 É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

2.3 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

3 Le convertisseur Pandoc

3.1 Généralités

«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.

3.2 Extensions à la syntaxe Markdown implémentées par Pandoc

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.

3.2.1 Encodage de fichiers

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.

3.2.2 Sauts de ligne

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.

3.2.3 Titres

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 titres

Titre avec Id et non numéroté

Titre stylé non numéroté

Lien vers le premier de ces 2 titres

Notez 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.

3.2.4 Styles et blocs

Pandoc implémente les styles supplémentaires suivants :

Une ~~portion de texte~~ barrée ! \
2^10^ vaut 1024 \
La molécule de l'eau est H~2~O

Une 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 !")
~~~~~~~
10
11
12
13
14
15
16
#!/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> HTML

Séquence de lignes dans lesquelles l'indentation est
   respectée, le formatage Markdown appliqué, y.c.
      définition de code, usage balises HTML

3.2.5 Formules TeX Math

L'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}\)

3.2.6 Figures

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 ![texte alternatif](URL_IMAGE "titre optionnel") 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 :

↲
![Légende de la figure...](markdown-large.png "Title...")
↲
Légende de la figure...

Légende de la figure...

3.2.7 Listes

Les extensions apportées par Pandoc à la syntaxe Markdown dans le domaine des listes sont nombreuses et particulièrement bienvenues.

3.2.7.1 Listes numérotées

Pandoc apporte aux listes numérotées les améliorations suivantes :

11. 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 suivant
  1. Liste dont la numérotation démarre au numéro spécifié
  2. Élément suivant, etc...
  1. Liste numérotée par des lettres majuscules
    1. sous-liste
    2. numérotée par des lettres minuscules
  2. Élément suivant (la lettre D est ici sans effet car ce n'est pas le 1er élément de la liste !)
  3. Etc...
  1. Liste numérotée par des chiffres romains majuscules
    1. sous-liste
    2. numérotée par des chiffres romains minuscules
  2. Élément suivant

Si 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\)

3.2.7.2 Liste numérotée référençable (une seule par document)

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...

  1. École polytechnique fédérale de Lausanne
  2. Faculté Environnement naturel, Architectural et Construit

Suite du document...

  1. Continuation de la liste
  2. Etc...

3.2.7.3 Listes de définitions

Les listes de définitions correspondent à la structure HTML suivante, un peu désuète bien que fort pratique :

<dl>
   <dt>terme</dt>
   <dd>définition 1</dd>
   <dd>définition 2</dd>
</dl>
terme
définition 1
définition 2

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...
EPFL

É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...

3.2.7.4 Autres remarques sur les listes

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 !
  1. éléments...
  2. de liste...

    subordonné au 2e élément de la liste !

  3. continuation de la liste !

Et ci-dessous modification de ce comportement :

  1. éléments...
  2. de liste...
bloc de code indépendant !
  1. nouvelle liste !

3.2.8 Notes de bas de page

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 :

  1. 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 ]

  2. 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:
<http://daringfireball.net/projects/markdown/>

Pandoc^[Pandoc: <http://johnmacfarlane.net/pandoc/>]
est un convertisseur de documents...

Markdown1 est une syntaxe légère d'écriture de documents.

Pandoc2 est un convertisseur de documents...

3.2.9 Tableaux

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 */

3.2.9.1 Tableau simple

La syntaxe de ce type de tableau est la suivante :

Le 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...


Légende du tableau...
Aligné à gauche Aligné à droite Texte centré
abcdef 1234 xyz

3.2.9.2 Tableau multiligne

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...


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 !

3.2.9.3 Tableau en grille

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 :

+----------------------------+-------+
| 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...


Légende du tableau...
En-tête etc...

Plusieurs lignes de texte dans la même cellule, mais toujours aligné à gauche !

  • liste
  • à puces

Texte formaté, code, etc...

  1. liste
  2. numérotée

3.2.9.4 Pipe table

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...


Légende du tableau...
Aligné à gauche Aligné à droite Texte centré Défaut
abcdef 1234 xyz etc
ghi jkl mno pqr 567890 ........ etc

3.2.10 Métadonnées du document (bloc de titre)

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 % :

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**
% [J.-D. Bonjour](mailto:jean-daniel.bonjour@epfl.ch), EPFL
% rév. 12.4.2013

suite du document...

3.2.11 Comportement de Pandoc par rapport au code HTML inclus

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 !

3.2.12 Gestion de citations et références bibliographiques

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").

3.2.13 Réalisation de slide shows HTML

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 :

Les 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
% <jean-daniel.bonjour@epfl.ch>, EPFL
% 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 :

![Automne](markdown-large.png "Image...")

Voyez le résultat sous forme de slide show :

Il est en outre possible de faire des slide shows PDF basés LaTeX beamer.

3.2.14 Possibilités de Pandoc en relation avec TeX/LaTeX

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 :

Pour davantage d'informations à ce sujet, voyez man pandoc sous Linux ou Mac OS X, ou le "Pandoc User's Guide" sous Windows.

3.2.15 Usage de templates Pandoc

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.

3.2.16 Autres possibilités en relation avec Pandoc

Il existe de nombreux outils liées à Pandoc (voir cette page). Mentionnons en particulier :

3.3 Installation de Pandoc

Les explications originales relatives à l'installation de Pandoc sont accessibles sur le site Pandoc.

3.3.1 Sous GNU/Linux

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 :

  1. installation préalable de la plateforme Haskell (langage de programmation fonctionnel dans lequel est écrit Pandoc) avec : sudo apt-get install haskell-platform (une soixantaine de packages seront installés occupant ~500 MB)
  2. puis installation/compilation proprement dite de Pandoc avec : 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
  3. l'installation s'effectue alors pour l'utilisateur courant dans le répertoire ~/.cabal (arborescence standalone qui pourrait être copiée sur une autre machine), l'exécutable étant ~/.cabal/bin/pandoc
  4. mettez à jour votre variable d'environnement PATH 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.

3.3.2 Sous Windows

Téléchargez l'installeur pandoc-<version>.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".

3.3.3 Sous Mac OS X

Téléchargez l'image-disque pandoc-<version>.dmg depuis ce lien. Ouvrez-la, lancez le pandoc-<version>.pkg et suivez les indications de cet installeur.

3.3.4 Quel que soit le système d'exploitation

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 :

Une alternative, présentée plus bas, consiste à effectuer une conversion Markdown → HTML avec Pandoc, puis HTML → PDF avec un autre outil.

3.4 Utilisation du convertisseur Pandoc

3.4.1 Syntaxe de la commande

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.in

Convertit le résultat de la concaténation des fichiers entree1.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 url

Convertit en "Markdown étendu" la page web correspondant à l'url spécifiée, et envoie le résultat sur la sortie standard.

pandoc -o sortie.odt entree.md

Convertit le fichier Markdown/Pandoc entree.md en un fichier sortie.odt au format ODF (LibreOffice Writer).

3.4.2 Options principales de la commande

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 :

3.4.2.1 Options générales

-o fichier.ext

Définit le nom du fichier de sortie, et déduit le format à 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 format

Définit explicitement le format 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 format

Définit explicitement le format 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 --standalone
Applique le template par défaut associé au type de fichier de sortie (voyez notre chapitre sur les templates). S'agissant d'une conversion en HTML, ce template (visible par la commande pandoc -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.

3.4.2.2 Conversion en HTML

-c fichier.css ou --css=fichier.css

Associe la feuille de style fichier.css au fichier HTML généré

-H header.html -B body.html -A footer.html

Insère respectivement :

Le fait d'utiliser l'une ou l'autre de ces options active implicitement l'option -s

--ascii

Convertit tous les caractères accentués en leur équivalent HTML (p.ex. &amp; pour &)

-S (S majuscule) ou --smart

Convertit certains caractères en leur équivalent typographique correct, par exemple : "guillemets" en “guillemets”, 'accents' en ‘accents’, ... en … (un seul caractère), --- en — (em-dash), etc...

--self-contained

Produit un document HTML entièrement standalone, c'est-à-dire sans dépendances externes. Les images sont ainsi incorporées sous la forme <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 !

3.4.2.3 Rendu des formules TeX Math en HTML

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 --latexmathml

Utilise le convertisseur LaTeXMathML dont le code JavaScript est automatiquement inséré dans le header HTML.

-s --mathml

Utilise un autre script MathML dont le code JavaScript est également automatiquement inséré dans le header HTML.

-s --mathjax

Utilise en ligne le script MathJax en insérant un lien dans le header HTML.

-s --jsmath=script.js

Utilise le script jsMath dont il s'agit de fournir le script.js

3.4.2.4 Numérotation des titres, table des matières

-N ou --number-sections

Numérote automatiquement les titres et sous-titres <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-contents

Incorpore une table des matières des titres. Sont collectés les titres du nombre de niveaux levels 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.

3.4.2.5 Conversion en PDF

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 :

  1. une conversion Markdown → HTML avec Pandoc
  2. puis une conversion HTML → PDF (associé à une bonne feuille de style CSS) par votre navigateur web et un driver d'impression PDF, ou directement en mode commande avec l'outil wkhtmltopdf

S'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).

3.4.2.6 Conversion dans d'autres formats

--reference-odt=fichier

Utilise le fichier ODT spécifié comme référence de styles pour la production d'un fichier ODT

--epub-stylesheet=fichier
Utilise le fichier CSS spécifié comme référence de styles pour la production d'un fichier ePub.

Il existe encore d'autres options --epub-*

3.4.2.7 Génération de slide shows

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

Critère de découpage du document en slides (voir explications plus haut).

-i ou --incremental

Cette option fera apparaître les éléments de listes progressivement à chaque clic de souris (sinon on passe directement au slide suivant). Sans cette option il est cependant possible de faire défiler une liste incrémentalement en la préfixant par > (générant <blockquote> en HTML).

Spécification du slide engine

-s -t s5 -i --slide-level=level_number --self-contained

Produit un slide show HTML au format S5 (Simple Standards-based Slide Show System). Avec l'option --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 :

-s -t slidy -i --slide-level=level_number --self-contained

Produit un slide show HTML au format Slidy. Avec l'option --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

Produit un slide show HTML au format Slideous. Avec l'option --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

Produit un slide show HTML au format DZSlides. Incorpore automatiquement dans le fichier HTML, même sans l'option --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

Produit un slide show HTML au format Revealjs. Incorpore dans le fichier HTML les données liées (images, codes JavaScript et CSS...). Pour produire le slide show, il faut cependant disposer, dans le dossier courant, d'un dossier reveal.js contenant les ressources Revealjs nécessaires (à télécharger depuis ce lien).

-t beamer

Produit un slide show PDF basé LaTeX beamer.

4 Quelques éditeurs adaptés à l'édition Markdown

Pour 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 :

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 [+] :

        #!/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"
        #!/bin/sh
        NOM_DOC=`echo $GEDIT_CURRENT_DOCUMENT_NAME | sed "s/\..*$//"`
        wkhtmltopdf "$NOM_DOC".html "$NOM_DOC".pdf

 


CC BY-SA , EPFL, ENAC-IT (2013-2014)                       (Page visitée fois depuis le 1-12-2013)


  1. Markdown: http://daringfireball.net/projects/markdown/

  2. Pandoc: http://johnmacfarlane.net/pandoc/