Convertir MD en PDF

C’est ce qui distingue cette conversion de toutes les autres conversions de documents du site. Un fichier Word connaît sa taille de page, ses marges et ses polices ; un fichier Markdown ne connaît rien de tout cela, car le format enregistre volontairement la structure et laisse l’apparence à ce qui le rend.

Toute décision sur la page — sa taille, ses marges, la police, l’endroit où tombe une rupture — est donc prise par le convertisseur, et aucune d’elles n’est dans votre fichier. C’est le pari du Markdown, et c’est en général un bon pari : le même document devient une page web, une présentation et un PDF sans être réécrit. Le coût apparaît ici, parce qu’un convertisseur à qui on n’a pas appris à lire le Markdown n’a rien à rendre et se rabat sur la composition des caractères.

Chaque caractère du fichier arrive sur la page, dans l’ordre, dans une seule police. Une ligne écrite ## Exigences est composée ## Exigences. Une puce écrite avec un trait d’union est une ligne qui commence par un trait d’union. Un bloc encadré conserve ses trois accents graves au-dessus et en-dessous. Le gras garde ses quatre astérisques. Rien n’est supprimé, rien n’est interprété, parce que le moteur documentaire derrière cette paire lit du texte et n’a jamais reçu de filtre Markdown.

Ce qui reste mérite d’être dit avec précision. Les sauts de ligne, les lignes vides et l’indentation sont conservés tels quels, si bien qu’un document dont la valeur tient à ses commandes et à sa configuration se convertit en quelque chose d’utilisable. Un document dont la valeur tient à sa hiérarchie de titres, non — et la bonne réponse est alors de rendre le Markdown dans l’outil où vous l’avez écrit, un aperçu d’éditeur, une construction de site statique, une chaîne de documentation, et d’imprimer le PDF à partir de là. Cette conversion sert à fixer le texte d’un fichier, pas à le mettre en page.

Un document Markdown qui montre six schémas ne contient aucun schéma. Il contient six chemins, et les images vivent à côté, sur le disque ou sur un serveur. Cela surprend les personnes qui convertissent pour la première fois, et c’est la raison la plus fréquente pour laquelle un PDF arrive avec des trous.

La correction consiste à faire en sorte que les chemins résolvent avant la conversion. Les chemins relatifs doivent pointer vers des fichiers qui accompagnent réellement le document ; les adresses web absolues dépendent d’un serveur joignable. Si les images sont le propos du document, c’est l’étape à réussir, plutôt que les réglages de la conversion.

Beaucoup de fichiers Markdown commencent par un bloc encadré de trois traits d’union contenant un titre, une date et quelques étiquettes. Les générateurs de sites statiques, les constructeurs de documentation et les applications de notes lisent ce bloc comme des métadonnées et le retirent avant de rendre quoi que ce soit.

Cette conversion ne connaît pas l’usage et imprime le bloc comme le reste, si bien que le PDF commence par trois traits d’union et une liste de paires clé-valeur avant que le document ne démarre. Supprimer le bloc avant la conversion est toute la correction, et cela vaut la peine de le faire sur une copie pour que l’original continue de fonctionner dans l’outil qui l’a écrit.

La description d’origine du Markdown, en 2004, était informelle ; CommonMark est la spécification précise que la plupart des outils suivent ; les tables en pipe, les listes de tâches, les notes de bas de page et le barré que tout le monde utilise sont des extensions par-dessus. Ce qu’un outil implémentait décidait en général du résultat d’un document.

Ce n’est pas la question ici. Rien n’implémente rien — ni le cœur ni les extensions — si bien qu’une table GitHub et un titre CommonMark sont traités de la même manière, comme des lignes de texte. C’est au moins prévisible : il n’y a pas de saveur à deviner, pas de moteur contre lequel tester, et ce que vous voyez dans votre éditeur coloration syntaxique désactivée est ce que le PDF contiendra.

Parce que le destinataire n’est pas vous. Un client, un juriste, un comité, un responsable conformité veut un document qu’il peut ouvrir, imprimer, annoter et classer — pas un fichier que sa machine propose d’ouvrir dans un éditeur de code, et pas un dépôt dans lequel il doit naviguer. Les dièses l’accompagnent, si bien que c’est une copie figée plutôt qu’une copie présentable.

Un PDF fige aussi l’état. Un README change chaque semaine ; un PDF qui en est tiré est ce qui était vrai le jour où il a été attaché à quelque chose, ce qui est exactement ce qu’une revue, un dépôt de dossier ou une annexe contractuelle demande. Continuez d’écrire en Markdown et exportez au moment où quelqu’un d’extérieur a besoin d’une copie.

Le HTML quand la destination est une page web ou un site de documentation, puisque le Markdown a été conçu comme un raccourci pour lui et que la conversion est plus proche d’une traduction que d’un rendu.

Le DOCX dans une situation précise et fréquente : le destinataire n’accepte qu’un fichier Word, et veut ajouter des révisions. Le Markdown n’a aucun flux de relecture, si bien qu’un document qui entre dans une série de commentaires est mieux remis en DOCX et relu ensuite — et le PDF est pour la version qui est terminée. Cette cible passe par le même moteur, si bien que la syntaxe arrive dans le fichier Word sous forme de texte aussi ; la différence est que le relecteur peut corriger un titre, ce qui est impossible dans un PDF.

Les formats bureautiques exigent un vrai moteur de documents, et celui-ci tourne sur notre serveur, contrairement aux conversions d’images. Le fichier voyage par une connexion chiffrée, est converti dans un environnement isolé qui n’a aucun chemin vers Internet, et les fichiers de travail sont supprimés dès que la tâche se termine.

La limite gratuite est de 25 mégaoctets, ce qui pour un document Markdown est en général décidé par la taille des images. Un fichier truffé de captures haute résolution l’atteint vite, et compresser les images en amont est la voie la plus rapide pour passer en-dessous.