1  Introduction

Markdown a évolué dans le temps :

• le CommonMark, format original, a été créé en 2004 pour produire des pages web¹ ;
• le Markdown Extra ajoute, par rapport au CommonMark, des tableaux, des abréviations, des notes en bas de page et des définitions. Il est par exemple utilisé pour les Wiki ou les CMS² comme Drupal ;
• le Github Markdown a aussi permis l’ajout de tableaux, des méthodes pour ajouter du code et l’utilisation de couleurs. C’est le format de tous les fichiers readme sur Github ;
• le Vanilla Flavored Markdown a amélioré les liens, permis l’inclusion de codes html et amélioré les listes (numérotation et indentation) ;
• enfin, le MultiMarkdown (assez proche du Pandoc Markdown utilisé dans le manuel) est plus orienté travail universitaire avec par exemple l’intégration et/ou l’amélioration des tables, des notes en bas de page, des références croisées ou des équations mathématiques.

En mars 2016, dans le but de standardiser le langage, deux RFC (appel à commentaires) ont été publiés :

• RFC 776314, qui introduit le type MIME text/markdown à partir de la variante originale de Markdown.
• RFC 776415, qui répertorie des variantes MultiMarkdown, GitHub Flavored Markdown (GFM), Pandoc, CommonMark, Markdown Extra et autres (source Wikipedia).

… Malgré son intérêt indéniable, il n’y a néanmoins toujours pas de norme associée à Markdown. C’est une critique régulièrement entendue.

1.1 Commandes de base

Les commandes de base du Pandoc Markdown présentées dans le manuel “Markdown & vous” sont communes à tous les formats générés. Ce sont les commandes relatives :

• à la structure du document (titres, paragraphes et listes) ;
• à la mise en forme du texte (gras, italique, indice et exposant…) ;
• aux compléments du texte (codes, notes, liens, figures, tableaux, équations, citations et bibliographie).

L’utilisation, par Pandoc de LaTeX pour produire des documents pdf permet d’ajouter de nombreuses fonctions proposées par LaTeX. C’est une manière d’utiliser LaTeX, avec la qualité esthétique des documents qu’il produit, via Markdown sans passer par l’édition d’un fichier LaTeX, pas toujours simple à maîtriser.

Ainsi, avec les fonctionnalités Markdown, les commandes LaTeX ajoutées, le tout converti avec Pandoc, rédiger des documents scientifiques de qualité sur la base de solutions ouvertes et low-tech devient possible (et accessible) pour le plus grand nombre.

1.2 LaTeX

1.2.1 Classes

Lorsqu’on travaille avec LaTeX, on doit d’abord déclarer une classe de document. Avec Markdown, pour la production de documents pdf, on va faire cette déclaration dans l’en-tête YAML (voir dans le manuel) avec la commande :

“documentclass: classe”.

Les principales classes possibles (sans les variantes) sont :

• article (la classe par défaut)
• report
• book
• letter (non décrit dans le manuel)
• beamer (créée à partir du module beamer et décrit dans le chapitre Beamer).

1.2.2 Paquets

Après avoir déclaré une classe, on peut modifier les fonctionnalités de LaTeX en ajoutant un ou plusieurs packages (ou “paquets”).

Avec Markdow, toujours dans l’en-tête YAML, on appelle ces paquets avec la commande :

\header-includes:

et, par exemple, pour modifier la langue du document :

\usepackage[french]{babel}

Les paquets peuvent :

• modifier la façon dont certaines parties de LaTeX fonctionnent ;
• changer l’apparence du document ;
• ajouter de nouvelles commandes qui seront utilisables par la suite dans la rédaction.

De nombreux exemples d’utilisation des paquets sont présentés dans les pages suivantes.

1.2.3 Format

Dans l’en-tête d’un document LaTeX (l’en-tête YAML pour un fichier Markdown), on va également définir certaines caractéristiques comme le format de la page (geometry:), la taille des caractères (fontsize:), la présence ou non d’une table des matières (toc:) ou la numérotation de titres (numbersections:).

1.2.4 Métadonnées

Dans l’en-tête YAML on va enfin ajouter les métadonnées (title, autor, keywords…).

Certaines de ces métadonnées apparaissent en en-tête du document pdf produit (voir Chapitre 2). Elles sont également utilisées pour les autres types de documents générés avec Pandoc (ePub, html…).

1.2.5 Templates

Il est aussi possible de se servir d’un template (modèle) qui sera appelé lors de la transformation avec Pandoc (–template=montemplate.tex).

Quelques références sont présentées dans le manuel.

---

1. Pour transformer un fichier .md en fichier .html avec la méthode historique, on va utiliser markdown.pl (une application PERL créé par J. Gruber). On peut retrouver la source ici : https://github.com/lauriro/markdown/tree/master.

2. Content Management System.