Mettre en forme un document Markdown en PDF

Ceci n'est pas un tutoriel, vous trouverez ici qu'un ensemble de trucs et astuces pour transformer un document .md en .pdf via l'outil Pandoc.

Pour différentes raisons, cette transformation n'est que peu documentée sur internet à ce jour (a fortiori en français). Tout ce qui suit a fait l'objet de recherche et de tests, et ont fonctionné pour moi.

Ci-dessous :

• Résoudre les problèmes d'accentuation et de caractères spéciaux ;
  
• Forcer la taille de l'interligne sur les templates LaTeX ;
  
• Retirer la numérotation du chapitre d'introduction ;
• Ajouter la numérotation des titres ;
• Formater les liens hypertextes ;
  

À savoir en premier lieu

Il faut savoir que Pandoc n'utilise pas ses propres outils pour produire un PDF, mais ceux de LaTeX.

Il en résulte que :

1. il faut choisir entre l'outil pdflatex ou l'outil xetex. Pour les documents en langue française, le second est à privilégier absolument pour éviter tout soucis de caractère spéciaux et d'accentuation. On indique sa préférence avec le paramètre --pdf-engine.

2. tous les paramètres de compilation et de mise en forme sont ceux de LaTeX, qu'il faut indiquer : soit dans un fichier séparé et appeler avec le paramètre -H de Pandoc ; soit dans le bloc YAML avec le paramètre header-includes.

3. les templates utilisés sont ceux de LaTeX : book, report, article mais aussi memoir. Plutôt que de créer un nouveau template de zéro pour votre document, il est vivement conseillé d'adapter ceux existants par petites touches, via des paquets et des commandes LaTeX.
   

Trucs et astuces

Résoudre les problèmes d'accentuation et de caractères spéciaux

Pour que les caractères spéciaux et accentués de votre ficher .md soient pris en compte correctement, mais aussi les règles typographiques de la langue française, il faut avoir choisi le compilateur xetex de LaTeX (ou alors le paquet babel avec l'outil pdflatex) et faire appel au paquet polyglossia (qu'il faut avoir installé), puis lui indiquer que votre langue est le français.

Ceci se fait tout simplement en indiquant dans le bloc YAML :

---
author: Jonathan Chibois
title: Compiler et mettre en forme un document Markdown en PDF
lang:fr
---

Forcer la taille de l'interligne sur les templates LaTeX

• Pour les templates book, article et report, il faut insérer la ligne suivante dans le bloc YAML :

---
author: Jonathan Chibois
title: Compiler et mettre en forme un document Markdown en PDF
lang:fr
header-includes:
    - \usepackage{setspace}\doublespacing
---

• Pour le template memoir, il faut insérer la ligne suivante dans le bloc YAML, en respectant scrupuleusement la casse des caractères :

---
author: Jonathan Chibois
title: Compiler et mettre en forme un document Markdown en PDF
lang:fr
header-includes:
    - \OnehalfSpacing
---

Retirer la numérotation d'un chapitre

Dans les class book ou memoir de LaTeX, les noms de chapitres sont automatiquement précédés de la mention « Chapitre » suivi du numéro de chapitre.

Or, il y a des chapitres, comme l'introduction ou la conclusion, pour lesquels cet ajout est superflu. Pour indiquer ces cas particuliers, il faut remplacer dans votre fichier .md :

# Introduction

par :

\chapter*{Introduction}

Ajouter la numérotation des titres

Par défaut, les classes LaTeX ne numérotent pas les titres. Seuls les chapitres le sont parfois (classes book et memoir, à ma connaissance).

Pour changer cela, il faut ajouter la ligne suivante dans le bloc YAML :

---
author: Jonathan Chibois
title: Compiler et mettre en forme un document Markdown en PDF
lang:fr
numbersections: true
header-includes:
    - \usepackage{setspace}\doublespacing
---

Formater les liens hypertextes

---
author: Jonathan Chibois
title: Compiler et mettre en forme un document Markdown en PDF
lang:fr
numbersections: true
header-includes:
    - \usepackage{setspace}\doublespacing
    - \renewcommand*{\UrlFont}{\ttfamily}

---

---
author: Jonathan Chibois
title: Compiler et mettre en forme un document Markdown en PDF
lang:fr
numbersections: true
header-includes:
    - \usepackage{setspace}\doublespacing
    - \usepackage{relsize}
    - \renewcommand*{\UrlFont}{\ttfamily\smaller\relax}

---