Avec Pandoc, disponible sous Linux, la conversion entre plus de quarante formats de fichiers devient une opération simple et rapide. De plus, cet outil s’avère idéal pour implémenter un système de documentation en tant que code (docs-as-code). Il suffit de rédiger vos textes en Markdown, de les stocker dans Git, puis de les publier dans le format souhaité.
Transformation de documents et la pratique du Docs-as-Code
Si vous possédez un document dans l’un des nombreux formats pris en charge par Pandoc, sa conversion vers un autre format ne posera aucun problème. C’est un atout majeur à avoir à portée de main.
Cependant, le véritable potentiel de Pandoc se révèle lorsque vous l’utilisez comme fondation pour un système simple de docs-as-code. L’idée derrière la documentation en tant que code est d’adopter les techniques et les principes du développement logiciel et de les appliquer à la création de documentation, notamment pour les projets de développement logiciel. Toutefois, cette approche est adaptable à tout type de documentation.
Les développeurs de logiciels utilisent leur éditeur de code ou environnement de développement intégré (IDE) favori pour écrire leurs applications. Le code saisi est enregistré dans des fichiers texte contenant le code source du programme.
Ils utilisent un système de contrôle de version, ou VCS (tel que Git, le plus populaire), pour enregistrer les modifications du code source au fur et à mesure de son développement et de son amélioration. Ceci permet aux programmeurs de conserver un historique complet de toutes les versions des fichiers de code source. Il est ainsi possible de retrouver rapidement toute version précédente d’un fichier. Git stocke ces fichiers dans un dépôt, qui peut être local sur l’ordinateur de chaque développeur et central, partagé et distant, souvent hébergé dans le cloud.
Quand une version fonctionnelle du programme est prête, les développeurs utilisent un compilateur pour lire le code source et générer un fichier exécutable binaire.
En rédigeant votre documentation dans un langage de balisage léger basé sur du texte, vous pouvez utiliser un VCS pour suivre l’évolution de vos écrits. Au moment de diffuser ou de publier un document, Pandoc vous permet de générer autant de versions différentes que nécessaire, qu’il s’agisse de documents pour le web (HTML), de traitement de texte ou de mise en page (LibreOffice, Microsoft Word, TeX), de format de document portable (PDF), de livre électronique (ePub), etc.
Tout cela est possible à partir d’un ensemble de fichiers texte légers gérés par un système de contrôle de version.
Installation de Pandoc
Pour installer Pandoc sur Ubuntu, entrez la commande suivante :
sudo apt-get install pandoc
Sur Fedora, la commande nécessaire est la suivante :
sudo dnf install pandoc
Sur Manjaro, vous devez saisir :
sudo pacman -Syu pandoc
Vous pouvez vérifier la version installée avec l’option –version :
pandoc --version
Utiliser Pandoc sans fichiers
Pandoc accepte aussi les saisies directes, si vous l’utilisez sans options de ligne de commande. Il vous suffit d’appuyer sur Ctrl + D pour signaler la fin de votre saisie. Par défaut, Pandoc s’attend à une entrée au format Markdown et génère une sortie HTML.
Voici un exemple :
pandoc
Nous avons saisi quelques lignes en Markdown et nous sommes sur le point d’appuyer sur Ctrl + D.
Dès que nous le faisons, Pandoc génère le code HTML correspondant.
Toutefois, pour une utilisation plus efficace de Pandoc, il est préférable de travailler avec des fichiers.
Les fondamentaux du Markdown
Le Markdown est un langage de balisage léger où certains caractères ont une signification particulière. Un simple éditeur de texte est suffisant pour créer un fichier Markdown.
Le Markdown est facile à lire, car il n’y a pas de balises visuellement intrusives qui détournent l’attention du texte. Le formatage des documents Markdown est similaire à la présentation qu’il représente. Voici quelques bases :
Pour mettre du texte en italique, encadrez-le d’astérisques. * _Ceci sera en italique_ *
Pour mettre du texte en gras, utilisez deux astérisques. **_Ceci sera en gras_**
Les titres sont indiqués par le symbole dièse (#). Le texte est séparé du dièse par un espace. Utilisez un dièse pour un titre de premier niveau, deux pour un deuxième niveau, et ainsi de suite.
Pour créer une liste à puces, commencez chaque ligne de la liste par un astérisque suivi d’un espace.
Pour créer une liste numérotée, commencez chaque ligne par un chiffre suivi d’un point, puis insérez un espace avant le texte.
Pour créer un lien hypertexte, mettez le texte du lien entre crochets ([]) et l’URL entre parenthèses [()] comme suit : [Lien vers le site](https://www.exemple.com/).
Pour insérer une image, placez un point d’exclamation avant les crochets (![]). Mettez un texte alternatif pour l’image entre crochets. Ensuite, saisissez le chemin d’accès à l’image entre parenthèses [()]. Voici un exemple : .
Nous explorerons d’autres exemples dans la section suivante.
Conversion de fichiers
La conversion de fichiers est simple. Pandoc peut habituellement identifier les formats de fichiers avec lesquels vous travaillez, en se basant sur leurs noms. Ici, nous allons générer un fichier HTML à partir d’un fichier Markdown. L’option -o (sortie) spécifie à Pandoc le nom du fichier à créer :
pandoc -o sample.html sample.md
Notre fichier Markdown de démonstration, sample.md, contient le court extrait de Markdown visible sur l’image ci-dessous.
Un fichier nommé sample.html est créé. Il suffit de double-cliquer dessus pour qu’il s’ouvre dans votre navigateur par défaut.
Générons maintenant un document texte au format OpenDocument que nous pourrons ouvrir dans LibreOffice Writer :
pandoc -o sample.odt sample.md
Le fichier ODT contient les mêmes informations que le fichier HTML.
Il est intéressant de noter que le texte alternatif de l’image est utilisé pour générer automatiquement une légende pour la figure.
Spécification des formats de fichier
Les options -f (from) et -t (to) permettent d’indiquer à Pandoc les formats de fichiers de départ et d’arrivée pour la conversion. Cela peut être utile si vous travaillez avec un format qui partage la même extension qu’un autre format associé. Par exemple, TeX et LaTeX utilisent tous les deux l’extension « .tex ».
Nous utilisons également l’option -s (standalone) pour que Pandoc génère tout le préambule LaTeX nécessaire pour que le document soit complet, autonome et correct. Sans l’option -s (autonome), la sortie serait toujours du LaTeX correct, mais qui serait destiné à être inséré dans un autre document LaTeX, et non pas interprété comme un document LaTeX autonome.
Saisissons la commande suivante :
pandoc -f markdown -t latex -s -o sample.tex sample.md
Si vous ouvrez le fichier « sample.tex » dans un éditeur de texte, vous verrez le code LaTeX généré. Si vous possédez un éditeur LaTeX, vous pouvez ouvrir le fichier TEX pour avoir un aperçu de l’interprétation des commandes de mise en page LaTeX. La réduction de la fenêtre pour qu’elle tienne dans l’image ci-dessous donne l’impression que l’écran est petit, mais en réalité, il est bien dimensionné.
Nous avons utilisé un éditeur LaTeX appelé Texmaker. Pour l’installer sur Ubuntu, entrez la commande suivante :
sudo apt-get install texmaker
Sur Fedora, la commande est :
sudo dnf install texmaker
Sur Manjaro, utilisez :
sudo pacman -Syu texmaker
Conversion de fichiers avec des modèles
Vous commencez sans doute à apprécier la polyvalence de Pandoc. Vous pouvez écrire une seule fois et publier dans pratiquement tous les formats. C’est un véritable tour de force, mais les documents peuvent manquer d’originalité.
Les modèles vous permettent de définir les styles utilisés par Pandoc lors de la création de documents. Vous pouvez par exemple demander à Pandoc d’utiliser les styles définis dans un fichier Feuilles de style en cascade (CSS) grâce à l’option –css.
Nous avons créé un petit fichier CSS avec le contenu suivant. Il ajuste l’espacement au-dessus et au-dessous du style de titre de niveau 1. Il change aussi la couleur du texte en blanc et celle de l’arrière-plan en une nuance de bleu :
h1 {
color: #FFFFFF;
background-color: #3C33FF;
margin-top: 0px;
margin-bottom: 1px;
}
Voici la commande complète – notez l’utilisation de l’option autonome (-s) :
pandoc -o sample.html -s --css sample.css sample.md
Pandoc utilise le style unique de notre fichier CSS minimaliste et l’applique au titre de niveau 1.
Une autre option de personnalisation possible lors de l’utilisation de fichiers HTML est d’inclure du balisage HTML dans votre fichier Markdown. Il sera retranscrit dans le fichier HTML généré comme du balisage HTML standard.
Cette méthode est à réserver pour les cas où vous ne générez que du HTML. Si vous travaillez avec plusieurs formats de fichiers, Pandoc ignorera le balisage HTML pour les fichiers autres que HTML, et il sera affiché tel quel dans ces fichiers.
Vous pouvez aussi définir les styles utilisés pour la génération de fichiers ODT. Ouvrez un document vierge dans LibreOffice Writer et ajustez les styles de titres et de police selon vos préférences. Dans notre exemple, nous avons aussi ajouté un en-tête et un pied de page. Enregistrez votre document sous « odt-template.odt ».
Vous pouvez maintenant l’utiliser comme modèle grâce à l’option –reference-doc :
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
Comparez cet exemple avec le précédent exemple de fichier ODT. Ce document utilise une police différente, possède des titres colorés et inclut des en-têtes et des pieds de page. Pourtant, il a été généré à partir du même fichier Markdown « sample.md ».
Les modèles de documents de référence peuvent être utilisés pour identifier les différentes étapes de production d’un document. Vous pourriez, par exemple, utiliser des modèles comportant des filigranes « Brouillon » ou « À réviser ». Un modèle sans filigrane serait utilisé pour le document finalisé.
Générer des PDF
Par défaut, Pandoc utilise le moteur LaTeX PDF pour générer des fichiers PDF. Le moyen le plus simple de s’assurer que les dépendances LaTeX nécessaires sont satisfaites est d’installer un éditeur LaTeX comme Texmaker.
Cependant, c’est une installation assez conséquente – TeX et LaTeX sont tous deux assez volumineux. Si l’espace de votre disque dur est limité ou si vous savez que vous n’utiliserez jamais TeX ou LaTeX, vous préférerez peut-être générer un fichier ODT. Vous pourrez ensuite l’ouvrir dans LibreOffice Writer et l’enregistrer au format PDF.
Documents en tant que code
L’utilisation de Markdown comme langage d’écriture présente plusieurs avantages, notamment :
Travailler dans des fichiers texte est rapide : ils se chargent plus rapidement que les fichiers de traitement de texte de taille similaire et on peut naviguer plus rapidement dans le document. De nombreux éditeurs, y compris gedit, Vim et Emacs, offrent la coloration syntaxique pour le texte Markdown.
Vous gardez un historique de toutes les versions de vos documents : Si vous enregistrez votre documentation dans un VCS comme Git, vous pouvez facilement identifier les différences entre deux versions du même fichier. Ceci est vraiment efficace uniquement lorsque les fichiers sont en texte brut, car c’est le format attendu par un VCS.
Un VCS peut enregistrer qui a effectué les modifications et quand : C’est particulièrement utile si vous collaborez fréquemment avec d’autres sur de grands projets. Il offre également un dépôt central pour les documents eux-mêmes. De nombreux services d’hébergement Git dans le cloud, comme GitHub, GitLab et BitBucket, proposent des plans gratuits dans leurs modèles de tarification.
Vous pouvez générer vos documents dans de nombreux formats : Avec quelques scripts shell simples, vous pouvez extraire les styles de fichiers CSS et de documents de référence. Si vous enregistrez vos documents dans un dépôt VCS intégré avec l’intégration continue et le déploiement continu (CI/CD), ils peuvent être générés automatiquement à chaque compilation du logiciel.
Dernières remarques
Il existe de nombreuses autres options et fonctionnalités dans Pandoc que nous n’avons pas abordées ici. Les processus de conversion pour la plupart des types de fichiers peuvent être personnalisés et affinés. Pour en savoir plus, consultez les excellents exemples sur le site officiel (et très détaillé) page web de Pandoc.