Convertir des fichiers avec Pandoc 🌳
12 juillet 2020 • 6 min 👓Salut à toi, jeune développeur !
Je déteste Microsoft Word. Non vraiment, je hais Word. Peut-être que ça vient du fait que je n’ai jamais vraiment pris la peine de bien le maîtriser.
Ou aussi peut-être qu’il m’est lié émotionnellement depuis la fac à des mauvais souvenirs de compte rendu de TP ou d’exposé à rendre avant midi alors qu’il est 11H55 et qu’on est à peine à 4 pages sur les 5 demandées, page de garde non comprise, et que ce p*tain de sommaire ne veut pas se mettre à jour.
Mais c’est fini tout ça. Récemment j’ai dû écrire une documentation développeur pour ma dernière mission. Le problème c’est que je l’ai écrite en Markdown, et je comptais le convertir en PDF. Sauf que le client voulait avoir accès à la doc, pour la modifier dans le futur.
Donc j’ai cherché un moyen de convertir facilement du markdown en Word, et je suis tombé sur Pandoc.
Introduction
Pandoc est un outil en ligne de commande permettant de convertir des fichiers de type markup en divers formats. Il peut notamment convertir dans les 2 sens :
- markdown (.md) <-> word (.docx)
- markdown <-> html
- markdown <-> lateX
- etc…
Il est utilisé habituellement pour écrire de la documentation technique, des papiers scientifiques et des livres. En savoir plus ici.
Installation
Je ne vais pas m’étaler longuement dessus, tu as juste à télécharger l’installeur sur le site officiel. Rien de spécial à ajouter.
Cependant pour la conversion en PDF, Pandoc utilise LateX par défaut. Tu devras donc installer une implémentation de LateX pour gérer les PDF, la doc officielle conseille MiKTeX.
Les bases
Pour utiliser Pandoc, tu as besoin d’un terminal. Sur windows, cmd ou powershell feront très bien l’affaire. Mais je te conseille quand même d’utiliser l’une de ces options:
Dans les exemples qui suivent on va partir du fichier Markdown ci-dessous, que j’ai appelé README.md:
---
title: 'Hello World'
author: 'John Doe'
date: '2020-07-12'
---
## Titre A
Lorem ipsum
### Sous titre A1
Lorem ipsum
- élément 1
- élément 2
- élément 3
## Titre B
Lorem ipsum
### Sous titre B1
> Lorem ipsum Quotes
### Sous titre B2
Lorem ipsum
Si tu ne connais pas le markdown, c’est un langage de markup. Il permet de formater du texte assez facilement. Tu peux l’apprendre très rapidement avec ce cheatsheet.
Un fichier markdown a l’extension .md. Et tu peux l’ouvrir avec n’importe quel éditeur de texte.
Convertir des fichiers
Pour convertir un fichier, il te suffit d’ouvrir un terminal dans le dossier où tu souhaites travailler tes fichiers et de taper la commande:
pandoc fichier_a_convertir -o fichier_cible
L’argument -o ici signifie output. Cet argument doit être suivi directement du nom de ton fichier cible.
Exemple: pour convertir notre fichier markdown README.md en fichier word README.docx, ça donne :
pandoc README.md -o README.docx
Un fichier README.docx se créera alors dans le même répertoire. Comme tu peux le constater, tous les éléments qu’on a renseigné dans le markdown se retrouvent joliment formaté dans word sans avoir eu besoin de toucher à l’interface de microsoft.
Les formats des fichiers sont implicitement renseignés par les extensions renseignés dans le nom, mais de manière alternative tu peux renseigner le format de chaque fichier avec les arguments suivants :
- -f (from) : format du fichier à convertir
- -t (to) : format du fichier cible
Exemple: la commande ci-dessous aboutit au même résultat que celle de l’exemple précédent:
pandoc README.md -f markdown -t docx -o README.docx
Convertir des fichiers avec un visuel personnalisé
Jusqu’à maintenant, les fichiers cibles sont produits avec un visuel par défaut. Mais tu peux personnaliser ce visuel (police, couleur, etc…).
Personnaliser un fichier word
Pandoc se sert d’un style par défaut contenu dans un fichier appelé reference.docx, pour convertir vers des fichiers word .docx.
Pour le personnaliser, tu dois d’abord faire une copie de reference.docx dans ton dossier de travail.
Pour cela, execute la commande suivante :
pandoc -o custom-reference.docx --print-default-data-file reference.docx
Après exécution, un fichier custom-reference.docx apparaît dans ton dossier. C’est ce fichier qui servira désormais de base pour la conversion vers un .docx. C’est un fichier word classique dans lequel tu peux modifier à ta guise les styles visuels.
Pour que Pandoc utilise custom-reference.docx comme base de style, tu dois le renseigner avec l’argument —reference-doc= suivi du chemin relatif vers custom-reference.docx
Exemple: on va produire un README.docx à partir de README.md mais avec un titre principal en rouge. Avant tout, tu dois modifier le style de title dans custom-reference.docx comme ceci.
Ensuite, tu exécutes la commande:
pandoc README.md --reference-doc=custom-reference.docx -o README.docx
Personnaliser un fichier html
La conversion en html marche aussi très bien, mais à l’inverse de la conversion en word, aucun style par défaut n’est appliqué par Pandoc.
pandoc README.md -s -o README.html
L’argument -s signifie standalone. Il permet de créer un fichier html complet dans le sens où le head avec les métadonnées seront aussi générés. Sans cet argument, tu auras juste un fragment du html.
Tu te retrouves alors avec un README.html comme ceci:
Pour cibler un fichier html personnalisé, tu peux le faire avec l’argument -c ou —css=. La valeur de l’argument étant un fichier .css.
Tu peux créer ton propre fichier css ou copier-coller l’exemple ci-dessous que j’ai nommé style.css:
@import url('https://fonts.googleapis.com/css2?family=Merriweather:wght@400;700&family=Montserrat:wght@400;700&display=swap');
* {
box-sizing: border-box;
}
body {
margin: auto;
max-width: 80vw;
padding: 2.5rem;
color: black;
font-family: 'Montserrat', sans-serif;
line-height: 140%;
color: #333;
}
img {
display: block;
margin: 0 auto;
max-width: 60%;
}
figcaption {
font-size: 1rem;
color: #757575;
text-align: center;
}
pre {
border: none;
border-radius: 5px;
background-color: #333;
color: #eee;
padding: 1rem;
}
code {
font-family: monospace;
font-size: 0.75rem;
}
h1,
h2,
h3,
h4,
h5,
h6 {
font-family: 'Merriweather', serif;
color: dodgerblue;
}
th,
td {
text-align: left;
padding-right: 1rem;
}
Ensuite, pour générer le fichier README.html stylisé:
pandoc README.md -s -c style.css -o README.html
Générer automatiquement le sommaire
Tu peux générer automatiquement un sommaire pour n’importe quel format de fichier qui s’y prête (docx, html, pdf, etc…). Pour cela, tu dois renseigner l’argument —toc (pour table of contents). Cet argument doit toujours être utilisé conjointement avec l’argument -s (pour standalone).
Exemple: re générons le fichier README.html à partir de README.md mais avec un sommaire cette fois-ci.
pandoc README.md -s -c style.css --toc -o README.html
Similairement, pour générer un fichier word README.docx avec le sommaire:
pandoc README.md -s --toc --reference-doc=custom-reference.docx -o README.docx
Remarque: à la première ouverture du fichier word généré avec sommaire, une boîte de dialoge apparaît, tu dois appuyer sur Oui pour que le sommaire soit produit.
Conclusion
Voilà, maintenant tu sais comment convertir n’importe quel fichier en d’autres formats. Si toi aussi tu n’aimes pas Word, tu peux maintenant te servir de ton nouveau super pouvoir pour faire de la doc.
Ce n’était qu’une petite introduction à Pandoc, je te conseille vivement de lire la documentation officielle pour en savoir plus. Notamment sur comment convertir en PDF (ça nécessite quelques étapes en plus).
En attendant, je te dis à la prochaine. Bisous!