Convertir du Markdown en PDF

Quel Markdown, et ce qu'il devient

Le Markdown est une famille plutôt qu'une spécification unique. Le socle commun — titres, emphase, listes, liens, images, citations, blocs de code — est le même partout, et au-delà chaque implémentation diffère. Ce qui est pris en charge ici, c'est le jeu étendu largement admis : tableaux, blocs de code délimités avec coloration syntaxique, listes de tâches, texte barré, notes de bas de page et front matter. Cela couvre ce que presque tout le monde écrit, et mieux vaut connaître la limite que la découvrir.

Les titres deviennent une vraie structure PDF et pas seulement du texte plus gros : ils portent des niveaux de plan, ce qui donne au PDF des signets pour naviguer. Les liens deviennent des annotations de lien fonctionnelles. Les blocs de code sont composés dans une police à chasse fixe avec coloration, ce qui fait toute la différence entre un document agréable à lire et un mur de gris. Le format de page et les marges sont choisis pour la lecture plutôt qu'hérités, puisqu'un fichier Markdown n'a aucun avis sur le papier.

Les images doivent être accessibles, et c'est la déception la plus fréquente. Un fichier Markdown fait référence à des images au lieu de les contenir : un chemin relatif ne se résout que si l'image est déposée avec le fichier, et une adresse web que si son serveur autorise d'autres sites à la récupérer. Une image introuvable est signalée dans le PDF au lieu de laisser un trou silencieux : un schéma manquant se voit, au lieu d'être découvert après l'envoi du document.

Deux éléments sont volontairement affichés sous forme de code plutôt que rendus. Les formules mathématiques en notation LaTeX et les diagrammes Mermaid exigent chacun leur propre moteur de rendu, et un rendu incorrect est pire que la source — une équation mal rendue est fausse d'une manière que personne ne peut voir. Le HTML brut dans le Markdown est pris en charge pour la mise en forme simple en ligne, pas pour la mise en page, car un bloc de balisage arbitraire n'a pas sa place dans un document paginé.

Si vous cherchez autre chose

Pandoc est l'outil sérieux pour cela, et il est gratuit. pandoc doc.md -o doc.pdf --pdf-engine=xelatex compose le document via LaTeX, ce qui donne un résultat vraiment soigné, avec une vraie césure, la gestion des lignes veuves et une vraie table des matières — et avec un modèle, vous contrôlez chaque aspect du design. Il affiche aussi correctement les formules LaTeX, précisément ce qui manque ici. Le prix à payer est l'installation d'une distribution TeX, qui n'est pas légère.

Pour de la documentation plutôt qu'un document ponctuel, un générateur de site statique ou mdBook produit mieux qu'un PDF : un résultat consultable, qu'on peut lier et lire sur un téléphone. Convertissez en PDF quand le document doit être imprimé, joint ou archivé — et gardez de toute façon le Markdown comme source de référence, car c'est la version qu'on peut modifier et comparer.