Imprimez Markdown avec élégance

La façon la plus rapide d'essayer mdprint est de commencer à taper dans l'éditeur de la page d'accueil. Il charge avec un document d'exemple qui met en œuvre chaque fonctionnalité - tableaux, code, math, diagrammes - pour que vous voyiez immédiatement à quoi ressemble une page finie. Supprimez l'exemple et tapez votre propre contenu, ou collez-le d'où vous l'avez écrit.

Si vous avez déjà un fichier Markdown sur votre ordinateur, vous avez deux façons de le charger. La première est de le glisser depuis votre gestionnaire de fichiers et de le déposer sur le panneau de l'éditeur. Un surlignage apparaîtra autour de la zone de dépôt pendant le glissement. Relâchez le fichier, et l'éditeur se remplit de son contenu. La seconde est de cliquer sur le bouton Importer dans la barre d'outils et de sélectionner le fichier dans le sélecteur. Les deux méthodes lisent le fichier localement - rien n'est envoyé.

mdprint accepte les fichiers .md, .markdown et .txt. L'extension .txt est utile pour les documents écrits en Markdown mais enregistrés avec une extension générique par un autre outil. Si vous essayez d'importer un fichier avec une autre extension, mdprint affichera une erreur et laissera votre contenu actuel intact.

Si vous n'avez jamais écrit en Markdown, les règles sont assez simples pour être apprises en cinq minutes. Vous écrivez en texte brut, et quatre caractères font l'essentiel du travail. Le symbole # en début de ligne crée un titre - un # pour le plus grand, six ###### pour le plus petit. Les symboles * et _ autour d'un mot le mettent en italique avec un de chaque côté et en gras avec deux. Le symbole - ou * en début de ligne crée une puce. Indentez de deux espaces pour imbriquer une puce sous une autre.

Le code se gère avec des accents graves. Un accent grave de chaque côté d'une expression la formate en `code en ligne`. Trois accents graves seuls sur une ligne ouvrent un bloc de code, et trois autres le ferment. Si vous mettez un nom de langage juste après les trois accents graves d'ouverture (```python, ```typescript, ```sql), le bloc de code reçoit la coloration syntaxique de cette langue. Sans indication de langage, le coloriseur essaie de deviner d'après le contenu, ce qui fonctionne souvent pour les langages populaires.

Liens et images utilisent tous deux des crochets et des parenthèses. Un lien est [le texte affiché](l'URL). Une image est la même chose avec un point d'exclamation devant : . Quand vous imprimez en PDF, les URL d'images pointant vers des serveurs publiquement accessibles seront récupérées et intégrées. Les images sur votre machine locale ou derrière une authentification ne s'afficheront pas - déposez-les directement dans l'éditeur sous forme d'URL data base64 si vous en avez besoin en ligne.

Les tableaux sont la seule partie de Markdown qui semble lourde dans la source mais s'affiche proprement. Une ligne d'en-tête, une ligne de séparation faite de tirets, et une ou plusieurs lignes de données, toutes séparées par des barres verticales. Les colonnes n'ont pas besoin d'être alignées dans la source - le moteur de rendu gère l'espacement. Ajoutez deux-points à une ou aux deux extrémités des tirets de la ligne de séparation pour contrôler l'alignement : :--- pour gauche, ---: pour droite, :---: pour centré.

Les équations mathématiques utilisent la syntaxe TeX entourée de dollars. Un dollar simple de chaque côté donne du math en ligne : $a^2 + b^2 = c^2$. Deux dollars sur leurs propres lignes donnent une équation en bloc, centrée sur sa propre ligne et plus grande. Toutes les commandes math LaTeX habituelles - \frac, \int, \sum, \sqrt, lettres grecques, matrices, l'ensemble de symboles AMS - fonctionnent parce que mdprint utilise KaTeX, qui implémente la même syntaxe.

Les diagrammes utilisent la syntaxe Mermaid dans un bloc de code délimité avec l'étiquette de langage mermaid. Le diagramme le plus simple est un organigramme : ouvrez avec graph LR (gauche-droite) ou graph TD (haut-bas), puis écrivez les nœuds connectés par des flèches. Mermaid prend aussi en charge les diagrammes de séquence (flux de messages entre acteurs dans le temps), les diagrammes de Gantt (chronologies de projet avec dépendances), les diagrammes de classes (relations entre objets) et les diagrammes d'état (machines à états). La documentation Mermaid contient des exemples pour chaque type.

Les notes de bas de page permettent de garder la prose lisible tout en ajoutant des citations détaillées ou des apartés. Marquez une note dans votre texte avec [^1] (le numéro peut être n'importe quoi - elles sont renumérotées en sortie). Quelque part dans le document, définissez la note avec [^1]: le contenu de la note. mdprint regroupe toutes les notes à la fin du document imprimé et ajoute des renvois qui lient chaque note à l'endroit où elle apparaît dans le texte.

Si votre document est long, insérez le texte littéral [[toc]] dans la source là où vous voulez qu'apparaisse une table des matières. mdprint le remplace par une liste imbriquée de liens vers chaque H2 et H3 du document. Dans le PDF imprimé, cette même table des matières devient un sommaire de navigation utilisable par les lecteurs PDF.

Ouvrez le panneau Paramètres depuis la barre d'outils pour contrôler la génération de votre PDF. Le format de page a deux options : A4 (la norme en dehors de l'Amérique du Nord) ou Letter (la norme en Amérique du Nord). L'orientation bascule entre portrait et paysage - paysage est utile pour les documents avec de larges tableaux ou diagrammes. Les marges offrent trois préréglages : étroites donnent plus de surface utile pour du contenu dense, normales sont le compromis conventionnel, et larges laissent de la place pour des annotations manuscrites sur une copie imprimée.

L'éditeur a ses propres thèmes clair et sombre, indépendants du reste de la page. Le bouton dans la barre d'outils bascule entre les deux. L'aperçu et la sortie imprimée restent en mode clair quoi qu'il arrive, car les fonds clairs s'impriment bien sur papier.

Si vous utilisez régulièrement le même ensemble d'options, votre dernière sélection est mémorisée localement et appliquée automatiquement la prochaine fois que vous ouvrez mdprint dans le même navigateur.

Le bouton Imprimer ouvre la boîte de dialogue d'impression native de votre navigateur. De là, tous les systèmes d'exploitation modernes offrent Enregistrer en PDF comme destination - Chrome, Firefox, Safari et Edge le prennent en charge sur macOS, Windows et Linux. Passer par la boîte de dialogue d'impression donne le plus de contrôle : vous pouvez choisir n'importe quelle imprimante, prévisualiser chaque page, changer l'orientation par page si votre pilote le permet, et sur certaines imprimantes vous pouvez changer les bacs à papier ou l'agrafage.

Le bouton Télécharger le PDF saute la boîte de dialogue et génère un fichier PDF directement dans le navigateur, puis déclenche un téléchargement. Il utilise vos paramètres actuels (format de page, orientation, marges) pour formater la sortie. Cette voie est plus rapide quand vous savez exactement ce que vous voulez et n'avez pas besoin de la flexibilité de la boîte de dialogue. Il fonctionne en rendant la page sous forme d'image haute résolution et en plaçant cette image dans le PDF, de sorte que le résultat correspond toujours à ce que vous voyez à l'écran. Le compromis : comme la page devient une image, le texte de ce PDF n'est ni sélectionnable ni consultable.

Les deux voies diffèrent par ce qui se retrouve dans le fichier. Enregistrer en PDF, via le bouton Imprimer, conserve le texte en tant que texte : il reste sélectionnable et consultable, reste net à n'importe quel zoom, et les diagrammes restent vectoriels. Télécharger le PDF est plutôt une capture image en un clic, donc rapide et fidèle au pixel, mais le texte n'y est pas sélectionnable. Utilisez Enregistrer en PDF quand vous voulez du texte sélectionnable ou le résultat le plus net à n'importe quel zoom ; utilisez Télécharger le PDF quand vous voulez juste une copie rapide et exacte de ce qui est à l'écran sans ouvrir la boîte de dialogue d'impression.

Sauts de page à des endroits gênants. mdprint évite de couper à l'intérieur des blocs de code, tableaux et diagrammes, mais ne devine pas pour la prose. Si un titre se retrouve en bas d'une page avec le contenu de la section sur la suivante, le plus simple est d'ajouter quelques phrases au-dessus ou en-dessous pour décaler le titre. Il n'y a pas de syntaxe manuelle de saut de page en V1 - l'ajouter est sur la liste V2.

Les images n'apparaissent pas dans le PDF. La cause la plus courante est une URL d'image qui pointe vers votre système de fichiers local (file://) ou vers un serveur n'autorisant pas l'accès cross-origin. Soit intégrez l'image en tant qu'URL data directement dans la source Markdown, soit envoyez-la sur un hébergeur d'images qui autorise l'accès public en lecture. Imgur, les serveurs user-content de GitHub et la plupart des CDN fonctionnent.

Les math ne s'affichent pas. Vérifiez la source pour des dollars non échappés dans du texte normal - un $ égaré peut démarrer une zone math qui avale le reste du paragraphe. Si vous avez besoin d'un dollar littéral dans la prose, échappez-le : \$. Si la syntaxe math est correcte mais que l'équation ne s'affiche toujours pas, la commande LaTeX n'est peut-être pas dans la liste prise en charge par KaTeX - la documentation KaTeX a une référence complète.

Le diagramme est vide. Mermaid est strict sur la syntaxe. Les erreurs les plus courantes sont un espace manquant après graph LR, un identifiant de nœud contenant un espace (utilisez camelCase ou des underscores), ou une flèche pointant vers un nœud non défini. Ouvrez la console développeur de votre navigateur - Mermaid affiche un message d'erreur spécifique lors d'un échec d'analyse.

Les tableaux s'enroulent bizarrement. Si un tableau est plus large que la page, mdprint le réduit à l'échelle pour qu'il rentre. Pour des tableaux très larges, passez en orientation paysage dans les Paramètres, ou restructurez le tableau en liste. Le PDF ne gère pas le défilement horizontal comme le web.

Utilisez les raccourcis clavier. Cmd+P (ou Ctrl+P sur Windows et Linux) ouvre la boîte de dialogue d'impression. Cmd+S (Ctrl+S) déclenche Télécharger le PDF. Les raccourcis propres au navigateur pour rechercher (Cmd+F), recharger (Cmd+R) et zoomer (Cmd+plus/moins) fonctionnent tous normalement - ils n'entrent pas en conflit avec mdprint.

Commencez chaque document par un H1. Le premier H1 devient le nom de fichier PDF suggéré, le titre du document pour l'accessibilité et le titre proéminent en haut de la page imprimée. Si vous commencez par H2 ou inférieur, le nom de fichier retombe sur 'document.pdf' et vous devrez le renommer manuellement après téléchargement.

Intégrez les images comme URL data quand la confidentialité importe. Si vous ne voulez pas qu'un lecteur PDF récupère des images depuis un serveur distant à l'ouverture de votre fichier, convertissez l'image en URL data base64 et intégrez-la directement. La plupart des systèmes d'exploitation ont un outil intégré ou dédié pour cette conversion. Le fichier résultant est plus volumineux, mais entièrement autonome.

Utilisez les listes de tâches pour les checklists imprimées. Si vous produisez une checklist papier - liste de bagages, checklist d'expédition, procédure pas à pas - utilisez la syntaxe de liste de tâches Markdown avec - [ ]. Les cases s'impriment comme des carrés que vous pouvez cocher au stylo.

Combinez mermaid et code dans la documentation technique. Un schéma courant consiste à montrer un organigramme d'un processus, suivi du code qui l'implémente. Markdown permet les deux dans le même fichier, et mdprint les rend d'une manière qui s'imprime proprement côte à côte.

Cmd+P ou Ctrl+P - ouvrir la boîte de dialogue d'impression.

Cmd+S ou Ctrl+S - télécharger en PDF.

Cmd+B ou Ctrl+B dans l'éditeur - mettre en gras le texte sélectionné.

Cmd+I ou Ctrl+I dans l'éditeur - mettre en italique le texte sélectionné.

Cmd+/ ou Ctrl+/ dans l'éditeur - basculer le commentaire pour la ligne courante (commentaire HTML en contexte Markdown).

Esc dans l'éditeur en plein écran - quitter le plein écran.