7 cas d’usage concrets pour transformer un README en PDF

Un lien vers un dépôt est excellent pour partager de la documentation avec quelqu’un qui vit déjà dans GitHub. C’est un mauvais moyen de la partager avec tous les autres. Les relecteurs perdent le contexte, les clients ne veulent pas créer de compte, et une URL n’est pas une archive. Le PDF règle le problème de diffusion, à condition d’être produit avec soin.

md2pdf s’articule autour d’un flux étroit : récupérer du Markdown depuis un dépôt public, un fichier local ou le presse-papiers ; le rendre avec le Markdown compatible GitHub ; appliquer une feuille de style d’impression ; puis l’envoyer à la boîte de dialogue « Enregistrer au format PDF » du navigateur. Cette étroitesse est utile. Elle permet au même outil de servir une transmission client de cinq pages comme un recueil de cours de cinquante pages, sans serveur, sans compte et sans envoi.

Voici sept situations où ce flux fait ses preuves, avec les réglages et la préparation qui font fonctionner chacune d’elles.

1. Transmissions clients et parties prenantes

Un client veut rarement un accès au dépôt juste pour lire une présentation de projet. Il veut un document qu’il peut ouvrir, transférer à un collègue et annoter en réunion. Un PDF de README offre souvent le bon niveau de détail : périmètre, notes d’architecture, étapes d’installation, captures d’écran et limites connues dans un seul fichier.

Configuration recommandée :

• Thème : Business pour un public externe, Clean pour un client très technique.
• Table des matières : activée au-delà de quatre pages.
• Format de page : celui de la région du client — A4 pour la majeure partie de l’Europe et de l’Asie, Letter pour les États-Unis et le Canada.
• Source : récupérez le dépôt s’il est public ; sinon, collez le Markdown ou importez le fichier README.

Préparation indispensable :

• Supprimez les liens vers des tickets internes, les URL de préproduction et les identifiants avant l’export. L’outil n’envoie pas le document, mais le PDF reste un fichier qui peut être transféré.
• Remplacez les chemins d’images relatifs par des chemins de dépôt qui existent réellement. md2pdf les résout lors de la récupération d’un dépôt, mais une image source cassée restera cassée dans le PDF.
• Vérifiez que le README s’ouvre sur un résumé, pas sur un journal des modifications. Un document de transmission doit dire au lecteur ce qu’est le projet avant de lui dire ce qui a changé.
• Ajoutez un court paragraphe « Comment lire ce document » si le README mêle instructions d’installation et contexte architectural.

Utilisez l’option de numérotation des pages du navigateur si le client doit renvoyer à des pages précises lors de la relecture. La feuille de style d’impression de l’application n’ajoute pas de numéros de page d’elle-même ; les en-têtes et pieds de page du navigateur sont le moyen le plus simple d’en obtenir.

2. Archives hors ligne et documentation de version

Une documentation qui n’existe que dans un dépôt change sous les pieds du lecteur. Lorsque vous avez besoin d’un instantané de ce à quoi ressemblait une version à un moment donné, le PDF est un artefact stable. Il peut être stocké à côté d’un binaire, joint à un enregistrement de version ou conservé dans les archives d’un projet sans craindre une réécriture future du README.

Configuration recommandée :

• Thème : Clean.
• Table des matières : activée.
• Nom de fichier : incluez le dépôt, le tag de version ou le commit, et la date, par exemple acme-api-v2.4.0-readme-2026-10-02.pdf.
• Source : récupérez le dépôt public, puis vérifiez que vous exportez bien le README voulu. L’application lit la branche par défaut ; utilisez donc le collage si vous avez besoin d’un tag ou d’un commit épinglé.

Préparation indispensable :

• Consignez la source quelque part dans le document ou dans le nom du fichier. Un PDF sans version n’est qu’une pièce jointe non datée de plus.
• Vérifiez les liens avant d’archiver. Un lien blob continue de pointer vers la branche par défaut du dépôt. Si vous avez besoin d’un véritable instantané d’un tag ou d’un commit, collez cette version du README au lieu de passer par la récupération, et notez le hash du commit dans une ligne de pied de page ou dans l’enregistrement de version associé.
• Désactivez les en-têtes et pieds de page du navigateur s’ils contiennent un chemin de fichier local ou un nom d’hôte interne. L’archive doit être autonome, pas révéler la machine qui l’a produite.
• Conservez la source Markdown à côté du PDF si l’archive doit être reproductible. Le PDF est l’artefact ; le Markdown est la recette.

C’est aussi un bon cas d’usage du thème Dark pendant la relecture : lisez l’aperçu à l’écran, puis exportez en sachant que la feuille de style d’impression l’éclaircira pour le papier. Vérifiez simplement le PDF final au lieu de supposer que l’apparence à l’écran est ce que recevra l’imprimante.

3. Candidatures universitaires et dossiers de cours

Les étudiants et les enseignants ont souvent des notes en Markdown, de la documentation de projet ou des recueils de lecture à remettre ou à distribuer sous forme d’un document unique. Academic remplit une fonction différente de celle d’un README produit : il a besoin d’un texte généreux, de blocs de code sobres et d’une mise en page qui ne ressemble pas à une page d’accueil.

Configuration recommandée :

• Thème : Academic.
• Table des matières : activée au-delà de trois sections.
• Format de page : suivez les exigences de l’établissement. A4 est courant hors des États-Unis ; Letter est courant aux États-Unis.
• Source : importez ou collez le Markdown si le travail n’est pas public. Ne placez jamais un travail inédit dans un dépôt public juste pour le convertir.

Préparation indispensable :

• Vérifiez la hiérarchie des titres avant l’export. Un recueil de cours aux niveaux sautés produit une table des matières confuse.
• Academic justifie le texte courant. Les URL très longues, les identifiants de code et les équations peuvent créer des espacements disgracieux. Transformez les URL longues en liens de type référence ou déplacez-les dans une section de type note de bas de page.
• Gardez les blocs de code courts. Le thème utilise un fond de code clair qui s’imprime bien, mais une ligne de 120 caractères débordera tout de même de la page.
• Si le document comporte des citations, conservez-les dans le Markdown sous forme de section de références. md2pdf rend le texte ; il ne gère pas de style de citation.
• Imprimez un brouillon avant de remettre. Le texte justifié et la typographie à empattements peuvent rendre différemment sur papier que dans l’aperçu.

Comme la conversion est côté client, les notes inédites et les articles en brouillon ne quittent pas le navigateur. C’est un avantage réel par rapport à un service du type « collez votre document dans notre convertisseur ».

4. Dossiers de relecture interne et notes de version

Les équipes d’ingénierie ont souvent besoin d’un document unique pour une revue de conception, une vérification de préparation de version ou un retour après incident. La source existe peut-être déjà sous forme de README ou de page de documentation. La transformer en PDF crée un ordre du jour figé pour la réunion et une trace de ce que les relecteurs ont vu.

Configuration recommandée :

• Thème : Clean pour les revues d’ingénierie, Business pour un public transversal.
• Table des matières : activée.
• Source : récupération d’un dépôt public, ou collage du Markdown si le dépôt est privé.

Préparation indispensable :

• Placez la décision ou la demande en tête. Un dossier de relecture qui commence par trois pages de contexte ne sera pas relu.
• Marquez explicitement les questions ouvertes. Le format PDF facilite l’annotation d’une copie imprimée, à condition que les questions soient visibles.
• Retirez les secrets et les identifiants clients. L’outil n’envoie le document nulle part, mais les dossiers de relecture ont tendance à être transférés.
• Incluez le commit ou la version du document dans le nom du fichier. Des notes de relecture sans version sont difficiles à rapprocher plus tard.
• Si le document contient des listes de tâches, vérifiez leur rendu. Les listes de tâches du Markdown compatible GitHub sont prises en charge, mais une longue liste de contrôle peut se scinder entre les pages. Gardez les éléments liés ensemble.

Les dépôts privés ne sont pas pris en charge par le flux de récupération. Pour un travail interne, le collage ou l’import est l’option pratique. Ce n’est pas un contournement ajouté après coup au produit ; c’est la manière prévue de traiter un contenu qui ne doit pas être lu depuis une URL publique.

5. Supports d’atelier et documents de conférence

Un exercice d’atelier qui vit dans un dépôt suppose un accès réseau, un compte GitHub et un ordinateur portable fonctionnel. Un support imprimé ne suppose rien de tout cela. Pour un tutoriel, une session de conférence ou un laboratoire en classe, un PDF est souvent l’exemplaire le plus fiable dans la salle.

Configuration recommandée :

• Thème : Business pour un support soigné, Clean pour un laboratoire riche en code.
• Table des matières : activée si le support comporte plusieurs exercices.
• Format de page : celui de l’imprimante du lieu. A4 et Letter sont tous deux courants ; vérifiez avant d’imprimer cinquante copies.
• Source : récupération du dépôt pour un dépôt d’atelier public, ou import pour un brouillon privé.

Préparation indispensable :

• Concevez pour les niveaux de gris. Un thème qui repose uniquement sur la couleur pour distinguer les sections perdra cette distinction sur une imprimante noir et blanc.
• Gardez les lignes de code sous environ 80 caractères. Un support se lit à bout de bras, pas sur un moniteur de 27 pouces.
• Ajoutez une URL courte ou un QR code vers le dépôt en ligne si les lecteurs ont besoin de la dernière version. Le PDF est la copie stable ; le dépôt est la version vivante.
• Vérifiez le nombre de pages. Un support de 40 pages n’est pas le même objet qu’une fiche d’exercices de 6 pages. Utilisez la table des matières et les titres pour décider de ce qui a sa place.
• Imprimez un exemplaire avant l’événement. Des réglages d’impression qui semblaient corrects à l’écran peuvent produire des marges différentes sur l’imprimante du lieu.

La feuille de style d’impression de l’application est conçue pour une pagination propre, mais elle ne peut pas savoir comment une imprimante précise gère les marges. Un seul essai d’impression reste la meilleure vérification qualité.

6. Demandes de subvention, portfolios et candidatures

Les candidatures demandent souvent une présentation de projet, un texte technique ou un exemple de portfolio en une seule pièce jointe. Un PDF de README peut convenir ici parce qu’il montre la documentation propre au projet sous une forme que le relecteur peut ouvrir sans compte GitHub.

Configuration recommandée :

• Thème : Business pour un public général, Academic pour une candidature orientée recherche.
• Table des matières : activée si le document dépasse quelques pages.
• Format de page : suivez les instructions de la candidature.
• Source : récupération d’un dépôt public, ou collage du Markdown si le projet est privé.

Préparation indispensable :

• Placez le projet le plus pertinent en premier. Les relecteurs de candidatures ne lisent parfois que les deux premières pages.
• Retirez les badges qui n’apportent pas de sens. Un mur de badges de build est du bruit dans une pièce jointe de portfolio.
• Assurez-vous que les captures d’écran et les schémas ont un texte alternatif et apparaissent réellement. Une image cassée est pire que pas d’image.
• Vérifiez que les liens sont cliquables dans le PDF. Un relecteur qui ne peut pas accéder au projet en ligne perd le contexte.
• Gardez une taille de fichier raisonnable. Les PDF très volumineux et riches en images peuvent atteindre les limites d’import des portails de candidature.

C’est aussi un cas où la typographie à empattements du thème Business peut aider un projet technique à se lire comme un document professionnel plutôt que comme un export brut de dépôt. Le contenu doit toujours porter la candidature ; le thème ne fait que donner le registre.

7. Instantanés d’audit et de conformité

Parfois, le but du PDF n’est pas d’être lu de bout en bout. Il est de prouver ce que la documentation disait à une date donnée. Un README qui décrit des contrôles d’accès, un traitement des données ou des procédures opérationnelles peut constituer une pièce utile d’un dossier d’audit lorsqu’il est capturé comme un artefact immuable.

Configuration recommandée :

• Thème : Clean.
• Table des matières : activée pour les documents longs.
• Nom de fichier : incluez le dépôt, le commit et la date de capture.
• Source : récupérez le dépôt public, ou collez le Markdown exact qui a été relu.

Préparation indispensable :

• Capturez la version source. Un PDF sans référence de commit est une preuve faible, car le README sous-jacent peut changer.
• Ne traitez pas le PDF comme un système d’enregistrement. C’est un instantané de documentation, pas un substitut aux journaux, politiques ou attestations signées.
• Vérifiez que le document ne contient pas de secrets, de noms d’hôtes internes ou de données personnelles. Un dossier d’audit est souvent partagé plus largement que le dépôt d’origine.
• Conservez la source Markdown et le PDF ensemble. Si quelqu’un conteste la capture, la source explique comment l’artefact a été produit.
• Réexportez lorsque la source change. Un PDF périmé portant un nom de fichier actuel est pire qu’un document manifestement daté.

Quand le PDF n’est pas le bon format

Un PDF est un format de diffusion, pas un format de collaboration. C’est le mauvais choix lorsque :

• Le document change tous les jours et les lecteurs ont besoin de la dernière version. Renvoyez plutôt vers le dépôt, ou générez le PDF selon un calendrier.
• Le contenu dépend d’éléments interactifs, de données en direct ou de vidéos intégrées. Le PDF aplatit tout cela.
• Le dépôt est privé et le destinataire doit parcourir la source. Un PDF lui donne un instantané, pas un accès.
• Le document tient en une seule page courte qui se lit parfaitement dans le dépôt. L’étape supplémentaire n’en vaut peut-être pas la peine.
• Vous avez besoin de commentaires et de suggestions suivis. Utilisez un outil de document collaboratif ; les annotations PDF ne remplacent pas les workflows de relecture.

L’outil n’est volontairement pas une plateforme de documentation. Il convertit un document que vous possédez déjà en un document portable. Savoir quand ne pas l’utiliser fait partie de la bonne manière de s’en servir.

Liste de vérification avant décollage en cinq minutes

Vérification	Pourquoi c’est important
La source est le bon dépôt ou le bon fichier	Un PDF avec le mauvais nom de projet est pire que pas de PDF
La hiérarchie des titres est cohérente	Elle contrôle la table des matières et la structure des pages
Les images s’affichent	Les chemins relatifs au dépôt nécessitent une récupération du dépôt
Les lignes de code ne sont pas trop larges	Les blocs de code larges sont le problème de troncature le plus courant
Les tableaux tiennent dans la page	Les tableaux à huit colonnes survivent rarement au A4
Les liens sont significatifs	Les liens blob et externes doivent rester compréhensibles hors ligne
Les textes confidentiels sont retirés	Le PDF peut être transféré même si la conversion est locale
Le thème correspond au public	Clean pour l’ingénierie, Business pour les clients, Academic pour les textes
Le format de page correspond au destinataire	A4 ou Letter change la pagination
Le nom de fichier inclut une version	Rend l’artefact traçable

Aide-mémoire des thèmes

• Clean — spécifications, README techniques, supports riches en code, audits.
• Business — transmissions clients, propositions, supports d’atelier, pièces de portfolio.
• Academic — dossiers de cours, articles, textes longs, candidatures de recherche.
• Dark — relecture à l’écran avant export ; la feuille de style d’impression l’éclaircit pour le papier.

En cas de doute, commencez par Clean, exportez un exemplaire et lisez-le sur un téléphone ou une page imprimée. Le thème qui semblait le meilleur sur un grand moniteur n’est pas toujours celui qui se lit le mieux à bout de bras.

Pour le processus complet, y compris les réglages d’impression et le dépannage, voir Comment convertir un README GitHub en PDF. Pour un examen plus approfondi des quatre thèmes, voir Clean vs Business vs Academic vs Dark.