Markdown en PDF

Le Markdown est un format d'écriture, délibérément proche du texte brut : lisible dans n'importe quel éditeur, comparable ligne à ligne dans un gestionnaire de versions, et exempt de l'état invisible qui rend les fichiers de traitement de texte pénibles à travailler à plusieurs. Ce qu'il n'est pas, c'est un format de diffusion. Un fichier .md remis à quelqu'un qui n'en a pas l'habitude est un fichier texte plein de dièses et d'astérisques.

Le PDF en est le complément. Il fige l'apparence, pagine le contenu, s'ouvre sur n'importe quoi sans éditeur ni moteur de rendu, et s'imprime correctement. Écrire en Markdown et livrer en PDF vous donne les deux moitiés : une source que vous pouvez garder dans un dépôt et relire comme du texte, et un objet que tout le monde peut lire.

Les cas typiques sont une documentation remise à un client, un README transformé en référence imprimable, des notes techniques pour une réunion, et des écrits universitaires ou personnels rédigés en texte brut et rendus sous forme de document.

Il existe deux façons de fabriquer un PDF depuis du Markdown, et elles produisent des fichiers très différents. Le raccourci consiste à rendre le Markdown comme une page web et à la photographier : c'est rapide et cela donne un document fait d'images — non consultable, non copiable, invisible aux lecteurs d'écran, et flou dès qu'on l'imprime à une autre taille que celle de la capture.

L'autre voie compose le contenu sur une vraie page : du texte tracé à partir de polices incorporées à des corps choisis, des paragraphes coulés sur une justification, des sauts de page placés entre les blocs plutôt qu'au travers. C'est ce qui se passe ici, et c'est pourquoi le résultat se comporte comme un document et non comme un diaporama d'images.

La différence se voit dans les gestes ordinaires que l'on fait ensuite avec un PDF. Chercher un terme fonctionne. Copier un extrait de code vous rend du code. Imprimer en A4 un document composé pour l'A4 donne des caractères nets à n'importe quel zoom.

Les titres deviennent une véritable hiérarchie de corps plutôt que du texte en gras : le document a donc une structure visible. L'emphase est rendue en italique et en gras. Les listes ordonnées et non ordonnées s'imbriquent correctement, avec des retraits qui rendent les niveaux lisibles. Les citations sont détachées du corps, et les filets horizontaux deviennent des filets.

Le code reçoit le traitement le plus soigneux, parce que c'est le moins tolérant. Le code en ligne est composé dans une chasse fixe pour se lire comme du code au milieu d'une phrase ; les blocs délimités conservent exactement leurs blancs et ne sont pas recomposés, puisque l'indentation a un sens dans la plupart des langages. La seule chose à vérifier sur un listing imprimé, c'est la largeur des lignes, car une page ne défile pas latéralement.

Les tableaux sont rendus avec des colonnes alignées et de véritables limites de cellules. Les liens conservent leur texte et restent visibles comme liens. Les images référencées dans la source sont placées dans le flux, à une taille qui tient dans la page.

Quelques habitudes améliorent le résultat plus que n'importe quel réglage. Employez un seul titre de premier niveau et imbriquez régulièrement en dessous — un document qui saute d'un titre de niveau un à un titre de niveau trois produit une hiérarchie qui paraît cassée sur une page, même si elle s'affiche très bien dans un navigateur.

Gardez les lignes de code sous quatre-vingts caractères environ là où le listing compte, car c'est à peu près ce qui tient confortablement sur une page en portrait dans une chasse fixe. Mieux vaut scinder un long tableau en deux plus étroits que laisser les colonnes se comprimer.

Pour les documents qui réclament des mathématiques, des schémas ou un aperçu en direct pendant la rédaction, l'Éditeur Markdown est le meilleur point de départ : il rend le LaTeX et les schémas Mermaid, enregistre automatiquement et exporte en PDF, Word et HTML. Markdown en Word est la voie à prendre quand le destinataire doit modifier plutôt que lire.