Créer une chaîne de publication avec Pandoc et Docker

Aujourd'hui, nous allons examiner de plus près comment les professionnels peuvent faire appel à Pandoc pour créer une chaîne de publication robuste et facile à mettre en œuvre. Pandoc est un outil extrêmement simple mais puissant qui permet aux utilisateurs de convertir des documents dans différents formats, en fonction de leurs besoins.

Cela peut grandement simplifier la documentation et la publication, ou même ouvrir quelques nouvelles possibilités d'automatisation. Mieux encore, Pandoc s'appuie sur Git-friendly Markdown, ce qui signifie que vous pouvez également implémenter un système de contrôle de version pour votre documentation sans aucun tracas supplémentaire.

En parlant de tracas, nous nous appuierons sur une image Docker pour installer Pandoc et LaTeX avec une simple traction. L'installation d'un logiciel peut prendre du temps et la configuration d'un environnement logiciel de travail à partir de zéro lors du démarrage d'un nouveau projet n'est guère productive. Docker aide à atténuer ces problèmes en permettant aux utilisateurs de tout configurer en quelques minutes, quelle que soit la plate-forme.

De plus, il n'est pas rare que les employeurs exigent que vous fournissiez votre propre matériel informatique. Ceci est souvent appelé Bring Your Own Device (BYOD), et n'oublions pas que la pandémie de COVID-19 a rendu le travail à domicile beaucoup plus répandu. Sans des solutions comme Docker, il serait difficile de prendre en charge des applications exécutées sur divers matériels et systèmes d'exploitation tels que Windows, macOS et Linux.

Commençons par examiner de plus près les conteneurs et les images Docker avant de passer à Pandoc.

Docker à la rescousse

L'utilisation de conteneurs Docker peut éliminer le besoin d'installer plusieurs applications logicielles sur une nouvelle machine. Des images Docker prédéfinies sont disponibles sur Docker Hub pour un grand nombre d'applications. Les principaux fournisseurs de cloud tels qu'AWS, Azure et Google fournissent tous des registres de conteneurs. Il existe de nombreux autres registres tiers, notamment GitLab et Red Hat OpenShift.

Il est probable qu'une image sera disponible pour la plupart (sinon la totalité) des applications. Cela signifie qu'il n'est pas nécessaire d'installer la plupart des applications et leurs dépendances. L'application peut simplement être exécutée dans un conteneur Docker. Cela élimine commodément les problèmes associés aux membres de l'équipe exécutant des applications sur différents matériels et différents systèmes d'exploitation. La même image peut être utilisée pour exécuter des conteneurs sur n'importe quel système capable de les exécuter, et les spécialistes Docker peuvent rendre ce processus extrêmement rapide et efficace.

Cas d'utilisation de Pandoc : documentation

La documentation peut être requise dans plusieurs formats différents. Le même document peut devoir être disponible dans différents formats tels que HTML pour les présentations et PDF pour les documents. La conversion entre les formats de fichiers peut être fastidieuse et nécessiter beaucoup de temps. Une bonne solution est d'avoir une chaîne de publication avec une seule source de vérité. Tous les documents doivent être rédigés dans la même langue. Il devrait s'agir d'un langage textuel car il est plus facile de versionner et de stocker dans les référentiels Git.

Markdown est un bon choix pour créer une source unique de vérité. Les logiciels capables de convertir des documents Markdown dans une variété d'autres formats sont facilement disponibles et ont tendance à être fiables.

Pandoc

Pandoc est un progiciel capable de convertir des documents en différents formats. En particulier, il peut convertir Markdown en HTML, PDF et autres formats largement utilisés. Le processus de conversion peut être personnalisé à l'aide de modèles et de métadonnées dans la source Markdown.

Pandoc nécessite une installation LaTeX pour créer des fichiers PDF. L'installation de Pandoc et LaTeX prend beaucoup de temps. Heureusement, il existe une image Docker appelée pandoc/latex , qui élimine le besoin d'installer autre chose que Docker.

Commandes Docker

Une image Docker appropriée doit être trouvée ou créée qui contient le logiciel nécessaire. Il est conseillé d'extraire l'image vers le registre local car le téléchargement peut prendre un certain temps.

 docker pull pandoc/latex

Pour exécuter une commande dans un conteneur Docker, un wrapper doit exécuter le conteneur Docker et exécuter une commande dans le conteneur. Une bonne solution consiste à écrire une fonction shell sur un système macOS ou UNIX/Linux. La fonction peut être placée dans n'importe quel script de connexion ou dans un fichier séparé tel que $HOME/.functions . Il est également possible d'écrire un script ou un alias avec la même fonctionnalité.

 function pandoc { echo pandoc $@ docker run -it --rm -v $PWD:/work -w /work pandoc/latex pandoc "$@" }

Cette fonction effectue les opérations suivantes :

• Il imprime la commande à l'écran.
• Il exécute un conteneur Docker à partir de l'image pandoc/latex .
• L'option -it crée une session de terminal interactif et rend visible la sortie de la commande.
• L'option --rm supprime le conteneur une fois la commande terminée.
• L'option -v $PWD:/work monte le répertoire courant sur l'hôte dans le répertoire /work du conteneur.
• Le -w /work fait du répertoire /work du conteneur le répertoire de travail.
• Le pandoc "$@" exécute la commande pandoc dans le conteneur en transmettant toutes les options de ligne de commande transmises à la fonction.

Un shell ou un script doit charger la fonction en mémoire.

 . $HOME/.functions

La fonction est maintenant une commande à part entière et se comporte de la même manière que si le binaire pandoc était installé localement. Cette approche peut être utilisée pour toute commande disponible dans une image Docker.

Markdown en HTML

Pour convertir Markdown en HTML, il est préférable d'utiliser un modèle et des métadonnées dans le Markdown.

Métadonnées Markdown

La source Markdown peut avoir une section d'en-tête qui peut avoir des métadonnées arbitraires. Les métadonnées prennent la forme de paires clé-valeur. Les valeurs peuvent être remplacées dans le modèle HTML.

 --- title: Document title links: prev: index next: page002 ...

L'en-tête commence par une ligne contenant seulement trois tirets --- . Il se termine par une ligne contenant seulement trois points ... . Les clés sont des mots simples suivis de deux-points et de sa valeur. Les clés peuvent être imbriquées. L'exemple montre la définition des clés appelées title, links.prev et links.next .

Cette approche utilise un fichier séparé pour chaque page. Dans l'exemple, la page précédente est index.md , la page actuelle est page001.md et la page suivante est page002.md . En pratique, des noms de fichiers plus significatifs seraient utilisés afin qu'il soit plus facile de réorganiser et d'insérer des pages.

Modèle HTML

Un modèle HTML est simplement un fichier HTML. Des substitutions de métadonnées et des structures de contrôle simples peuvent être ajoutées entre les symboles dollar. Voici un exemple simple de modèle HTML pour Pandoc :

 <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>$title$</title> <link href="../css/style.css" type="text/css" rel="stylesheet" /> </head> <header> <h1>$title$</h1> </header> <body> $body$ </body> <footer> $if(links.prev)$ <a href="$links.prev$.html" class="previous">&laquo; Previous</a> $endif$ $if(links.next)$ <a href="$links.next$.html" class="next">Next &raquo;</a> $endif$ </footer> </html>

L'exemple montre un modèle. Le $body$ est remplacé par le texte Markdown converti en HTML. Les instructions conditionnelles ne génèrent le lien HTML que si les métadonnées sont définies dans l'en-tête Markdown.

Générer du HTML à partir de Markdown

Pandoc a juste besoin d'être informé du nom des fichiers d'entrée et de sortie, ainsi que des fichiers de modèle. Le format de fichier d'entrée par défaut est Markdown . Il peut déduire le format du fichier de sortie à partir de l'extension de fichier de sortie spécifiée.

Les commandes pour générer des sorties peuvent être un script ou un makefile.

 dir=Project for input_file in ${dir}/*.md do output_file=HTML/${input_file%.md}.html if [[ ${input_file} -nt ${output_file} ]] then pandoc --data-dir . --template presentations.html -t html \ -o ${output_file} ${input_file} fi done

Pour chaque fichier .md dans le répertoire du Project , il crée un fichier .html correspondant dans le répertoire HTML/Project si le fichier de sortie est plus ancien que le fichier d'entrée ou n'existe pas.

Génération de PDF Beamer à partir de Markdown

Beamer est un package LaTeX pour produire des présentations. La sortie est un diaporama PDF.

Les mêmes fichiers source Markdown peuvent être utilisés pour générer le PDF Beamer.

 pandoc -t beamer -o PDF/Project.pdf -V theme:Boadilla -V colortheme:whale Project/index.md Project/page000.md

Les détails de la commande sont :

• L'option -t beamer indique d'utiliser LaTeX et beamer pour générer le PDF.
• L'option -o spécifie le fichier de sortie.
• Les options -V sélectionnent le thème du projecteur et le thème de couleur.
• La commande se termine par une liste de fichiers Markdown qui seront concaténés dans l'ordre indiqué.

Tout le traitement est effectué dans un conteneur Docker.

Markdown au format PDF

La conversion d'un document Markdown en document PDF est également assez simple. Le PDF est toujours généré en convertissant d'abord le Markdown en LaTeX. Des métadonnées peuvent être ajoutées à l'en-tête Markdown pour personnaliser la sortie, par exemple en définissant le format du papier et la taille de la marge.

 --- title: Title of document papersize: a4 geometry: - margin=20mm ...

Génération de PDF à partir de Markdown

La commande pour convertir le Markdown en PDF est simple :

 pandoc -s Project/outline.md -o PDF/ProjectOutline.pdf

L'option -s crée un document autonome.

Conclusion

Il n'est plus nécessaire de passer plusieurs jours à installer un logiciel. Le simple fait d'exécuter une commande dans un conteneur Docker élimine le besoin d'installation. De nombreuses applications ont des images Docker appropriées sur Docker Hub. Si le logiciel doit être mis à jour, extrayez simplement la dernière image Docker.

La configuration d'un nouvel ordinateur consiste simplement à installer Docker, à extraire les images nécessaires et à créer quelques scripts.

Il n'est plus nécessaire de créer des documents dans différents formats. Un format unique tel que Markdown peut être utilisé pour tous les documents. Des outils tels que Pandoc peuvent ensuite générer des documents à partir de Markdown dans un grand nombre de formats différents.

Comme Markdown est un fichier texte, lorsqu'il est archivé dans un référentiel Git, un historique complet des versions est disponible. Les référentiels Git rendent également automatiquement Markdown et permettent aux utilisateurs de commenter les modifications sans avoir à utiliser des historiques de modifications désordonnés dans le fichier de document lui-même.