A few months ago, I wrote an article on using LaTeX to easily manage and track a CV. I ended up using LaTeX instead of my first choice (Markdown + HTML Stylesheets), because I had a great deal of trouble getting the page sizing working properly. Since then, I’ve learned a fair bit more, and want to share my knowledge with you!
Il y a quelques mois, j'ai écrit un article sur l'utilisation de LaTeX pour facilement gérer et mettre à jour un CV. J'ai fini par utiliser LaTeX plutôt que mon premier choix (Markdown + les feuilles de styles du HTML), parce que faire fonctionner le dimensionnement de la page correctement me posait de gros problèmes. J'en ai appris un peu plus et je veux partager mes connaissances avec vous !
The Path Shortly after writing the article mentioned above, I heard about Adam Wathan typesetting the book “Refactoring UI” in Markdown and generating PDFs from those files. He informed me on Twitter that he was using Prince XML to compile the PDF files. Looking into it, I decided it was way too expensive for the occasional (commercial) use that I was planning. It did, however, indicate to me that this was possible. If you’re looking for a free tool for personal use, Prince does allow it, and only adds a small logo on the first page. Instead, I then headed to alternativeto.net and had a look at the alternatives to Prince XML. There were 3 options listed - wkhtmltopdf, PDFReactor, and WeasyPrint. PDFReactor also has a licensing cost associated with it, so I instead focused on the other two.
Le cheminement
Peu de temps après avoir écrit l'article mentionné ci-dessus, j'ai entendu qu'Adam Wathan composait son livre « Refactoring UI » (Refaire une interface utilisateur) en Markdown et générait ses PDF à partir de ces fichiers. Il m'a informé sur Twitter qu'il utilisait Prince XML pour compiler les fichiers PDF. En regardant ça, j'ai décidé que c'était une solution trop chère pour l'usage (professionnel) occasionnel que je prévoyais. Mais cela m'a démontré que c'était possible. Si vous cherchez un outil gratuit pour un usage personnel, Prince l'autorise bien, et n'ajoute qu'un petit logo sur la première page.
À la place, j'ai filé ensuite sur alternativeto.net et cherché des alternatives à Prince XML. Trois options étaient proposées : wkhtmltopdf, PDFReactor et WeasyPrint. PDFReactor nécessite l'achat d'une licence ; aussi, je me suis concentré sur les deux autres.
WeasyPrint My first look was WeasyPrint, as it looked the most similar to Prince XML. It takes a website, and turns it into a wonderful PDF. If you need to make brochures, or documents with images/diagrams/icons, this would probably be my recommendation. It’s not too complicated to set up and use, but it does require you to create the HTML file somehow, including all the assets and styles. Combining this with Tailwind CSS would probably be the fastest way to create a nice looking PDF. However, I wanted something similar - just a set of Markdown files that could be turned into basic text-only PDFs.
WeasyPrint
Mon premier regard a été pour WeasyPrint, car il ressemblait le plus à Prince XML. Il prend un site Web et le transforme en un merveilleux PDF. Si vous avez besoin de faire des brochures, ou des documents avec des images/graphiques/icônes, ce serait probablement ma recommandation. Il n'est pas trop compliqué à paramétrer et utiliser, mais il vous oblige à créer le fichier HTML d'une façon ou d'une autre, en incluant tous les éléments fixes et les styles. Une combinaison avec Tailwind CSS serait probablement la façon la plus rapide de créer un PDF au bel aspect. Cependant, je voulais quelque chose de similaire, juste un ensemble de fichiers MarkDown qui puissent être transformés en PDF de base, avec seulement du texte.
wkhtmltopdf This engine can be used with Pandoc (which I have previously used to turn .docx files into Markdown), and can take Markdown files directly, and, with one command, generate the HTML and then the PDF. You can include CSS files and many other options. Admittedly, I haven’t found too many easy-to-follow guides, and I find their documentation to be confusing when you have little experience with pandoc. As a side note, pandoc also supports weasyprint.
wkhtmltopdf
Ce moteur peut être utilisé avec Pandoc (que j'ai déjà utilisé pour transformer des fichiers .docx en MarkDown). Il peut prendre directement des fichiers MarkDown et, avec une seule commande, il génère le HTML puis le PDF. Vous pouvez inclure des fichiers CSS et beaucoup d'autres options. J'admets que je n'ai pas encore trouvé trop de guides faciles à suivre et je pense que leur documentation est confuse quand vous avez peu d'expérience de pandoc. Remarque, pandoc supporte aussi weasyprint.
Reddit to the Rescue While I had done a few tests, I didn’t have the time to invest in creating decent styles for either tool, especially since that was where I ran into the most issues originally. Instead, I put it on the back burner and continued working on my various other projects. That is, until the first week of February, where a user had posted on Reddit’s /r/unixporn subreddit. His setup included a very nice PDF generated from a very normal-looking Markdown file. Hunting through the comments, I found someone who had already asked the question of “how?”. Well…it turns out to have been pandoc + wkhtmltopdf. Following the dialog (and the recommendation of tufte-css), I have successfully compiled a few easy Markdown files into usable, readable PDFs.
Reddit à la rescousse
Comme je n'ai fait que quelques tests rapides, je n'ai pas eu le temps de m'investir dans la création de styles décents pour l'un ou l'autre des outils, surtout parce que c'est là où j'ai eu le plus de problèmes initialement. À la place, je l'ai mis de côté et j'ai continué à travailler sur mes divers autres projets. Et ce, jusqu'à la première semaine de février, quand un utilisateur a posté un message à propos de /r/unixporn subreddit de Reddit. Son paramétrage incluait un très joli PDF généré à partir d'un fichier MarkDown à l'aspect ordinaire. En parcourant les commentaires, j'ai trouvé quelqu'un qui avait déjà posé la question du « comment ? ».
Eh bien…, il s'avère que c'était pandoc + wkhtmltopdf. En suivant dans la boîte de dialogue (et la recommandation de tufte-css), j'ai compilé avec succès quelques fichiers simples en MarkDown en fichiers PDF utilisables et lisibles.
Why? I’ve heard this question a lot when it comes to things I spend my time investigating. The answer for this one is also pretty standard - efficiency. As a developer, I often have to write documentation or make notes about some process or another. When I expect to have upwards of 5 pages of documentation (especially with images, an index, etc), I stick with Sphinx. This is extra useful, as I can output to LaTeX, PDF, ePub, or HTML (among other things). Depending on the needs of my client, I can then compile the same files into any combination of formats they might need. However, if I’m looking at maybe a single page of documentation, setting up Sphinx is a massive overkill for this kind of situation. Especially if it’s not for a client and I just want to keep track of some process I used. I tend to write this stuff into Markdown (even before I could compile it into PDF easily) because I sometimes want to collect various items together, or add it to my internal documentation (which is HTML created from Markdown). Therefore, writing the short notes into Markdown was always my first approach. Now I can compile the Markdown into HTML (as normal), but also into PDFs for longer-term storage or sharing.
Pourquoi ?
J'ai beaucoup entendu cette question à propos des sujets que je passe mon temps à investiguer. La réponse à celle-ci est aussi très ordinaire : l'efficacité. Comme développeur, je dois souvent écrire de la documentation et faire des notes sur des processus ou autres. Quand je m'attends à avoir 5 pages de documentation (surtout avec des images, un index, etc.), je préfère Sphinx. Celui-ci est vraiment utile, car je peux sortir en LaTeX, PDF, ePub ou HTML (entre autres). Suivant les besoins de mon client, je peux compiler les mêmes fichiers dans n'importe quelle combinaison de formats dont il pourrait avoir besoin.
Cependant, si je n'envisage qu'une unique page de documentation, paramétrer Sphinx est une énorme perte de temps. Particulièrement si ce n'est pas pour un client et que je veux juste garder une trace d'un processus que j'ai utilisé. Je tends à écrire ce genre de choses en MarkDown (même avant que je puisse le compiler facilement en PDF), parce que, parfois, je veux regrouper des sujets variés ou l'ajouter à ma documentation interne (qui est en HTML créé à partir de MarkDown). Ainsi, donc, écrire des courtes notes en MarkDown a toujours été ma première approche. Maintenant, je peux compiler le MarkDown en HTML (comme d'habitude), mais aussi en PDF pour un stockage à long terme ou un partage.
I also find Markdown much faster to type and format than anything like Google Drive, Microsoft Word, or Pages documents, since formatting is taken care of with just a few characters, instead of memorizing ever-changing (between the various applications) shortcuts, or having to use the mouse to select individual styles and settings. Best of all, Markdown is repeatable. I can write a dozen documents, and format them all the same way at the same time with one CSS file.
Je trouve aussi que le MarkDown est beaucoup plus rapide à saisir et à formater que d'autres, comme les documents Google Drive, Microsoft Word ou Page, car le formatage est réalisé avec quelques caractères, au lieu de devoir mémoriser des raccourcis toujours changeants (d'une application à l'autre), ou en devant utiliser la souris pour sélectionner les styles individuels et les paramètres. Le meilleur c'est que MarkDown est répétable. Je peux écrire une douzaine de documents et les formater tous de la même manière au même moment avec un seul fichier CSS.
How? This is surprisingly simple. Using the links in the Further Reading section, make sure you’ve downloaded the Tufte CSS file and fonts (or any CSS file you’d like to use), and save them somewhere. After that, make yourself a Markdown file you’d like to convert. Then use the command below: pandoc -f markdown -t html5 ./fcm-notes/pandoc.md –pdf-engine wkhtmltopdf –css tufte.css -o “pandoc.pdf” The options are pretty self-explanatory - f for the input format (“from”), -t for the target format (“to”), –pdf-engine for the engine to use, –css for the target CSS file, -o for the output file name. You can also get fancier by creating a script to watch a specific file, or a bash alias to speed up the process of compiling a file. Either way, this should get you started!
Comment ?
C'est surprenant de simplicité. En utilisant les liens de la section « Pour aller plus loin », assurez-vous que vous avez téléchargé le fichier Tufte CSS et les polices (ou n'importe quel fichier CSS que vous souhaitez utiliser), et sauvegardez-les quelque part. Après cela, faites un fichier en MarkDown que vous aimeriez convertir. Puis utilisez la commande ci-dessous :
pandoc -f markdown -t html5 ./fcm-notes/pandoc.md –pdf-engine wkhtmltopdf –css tufte.css -o “pandoc.pdf”
Les options se comprennent facilement : -f pour le format d'entrée (« from », à partir de), -t pour le format cible (« to », vers), –pdf-engine pour le moteur à utiliser, –css pour le fichier CSS cible, -o pour le nom du fichier de sortie (« output », sortie).
Vous pouvez aussi faire plus compliqué en créant un script pour viser un fichier particulier, ou un alias bash pour accélérer le processus de compilation de fichier. Quoi qu'il en soit, ceci vous permettra de démarrer !
Future Now that I have the Markdown → PDF workflow working, I will see about using pandoc to convert Markdown into Doc formats. This way, I can start writing Markdown files for articles, and host them internally as a website for easy searching, instead of hunting through a folder of Word and google documents.
L'avenir
Maintenant que je dispose d'une enchaînement du MarkDown vers le PDF qui fonctionne, j'envisagerai d'utiliser pandoc pour convertir du MarkDown aux formats Doc. De cette façon, je peux commencer à écrire des fichiers MarkDown pour des articles et les héberger en interne comme des sites Web pour une recherche facile, plutôt que les pister dans un dossier plein de documents Word ou Google.
Conclusion While Pandoc can do an almost overwhelming amount of things, starting with a few simple (but powerful) options seems best. From there, you can move on to creating slideshows, or any number of other formats. Have you ever used this? Or are you inspired to do so now? Feel free to share any awesome use-cases with me via email. Or reach out to me at lswest34+fcm@gmail.com with any recommendations, questions, or article requests.
Conclusion
Bien que Pandoc puisse faire une énorme quantité de choses, un début avec quelques options simples (mais puissantes) semblent le mieux. De là, vous pouvez passer à la création de diaporamas en reveal.js, ou un grand nombre d'autres formats. L'avez-vous déjà utilisé ? Ou aimeriez-vous l'utiliser maintenant ? N'hésitez pas à partager n'importe quel cas d'utilisation fantastique avec moi par mail. Ou écrivez-moi à lswest34+fcm@gmail.com avec vos recommandations, questions ou demandes d'articles.
Further Reading https://www.reddit.com/r/unixporn/comments/al1uge/i3wm_my_comfy_notetaking_setup/ - Reddit thread https://pandoc.org/MANUAL.html - Pandoc manual https://weasyprint.org/ - WeasyPrint https://github.com/edwardtufte/tufte-css - Tufte CSS repo
Pour aller plus loin
https://www.reddit.com/r/unixporn/comments/al1uge/i3wm_my_comfy_notetaking_setup/ - Un fil sur Reddit
https://pandoc.org/MANUAL.html - manuel Pandoc
https://weasyprint.org/ - WeasyPrint
https://github.com/edwardtufte/tufte-css - Dépôt de Tufte CSS