Qu’est-ce qu’un fichier MD ?

MD est un format texte que n’importe quel éditeur ouvre. Il est utilisé pour la retouche et l’échange entre programmes.

L’extension est .md et le nom complet Markdown. L’un et l’autre comptent moins que ce que le fichier peut contenir, et c’est le sujet du reste de cette page.

Il remonte à 2004. La spécification est CommonMark.

L’âge est utile à connaître pour une raison pratique : plus un format est ancien, plus les programmes ont eu le temps de l’apprendre.

Elle est publiée intégralement : n’importe qui peut l’implémenter à partir du document plutôt qu’en l’observant, et c’est pourquoi ce format apparaît dans tant de programmes et pourquoi des fichiers écrits il y a vingt ans s’ouvrent encore. Une spécification publiée n’est pas pour autant libre de redevances : quand un format enveloppe un codec, les brevets sont une question à part, que la norme ne tranche pas.

Visual Studio Code, Obsidian et Typora le lisent, comme la plupart des programmes du même genre.

Quand un fichier ne s’ouvre pas, le format est rarement en cause : le plus souvent, c’est le programme qui est plus ancien que lui. Convertir vers quelque chose de plus ancien est le contournement fiable, et c’est à cela que sert le reste de ce site.

Aucun navigateur ne le lit.

C’est de loin la raison la plus fréquente de le convertir : non pas que le format soit mauvais, mais que l’endroit où vous voulez montrer le fichier ne sache pas le lire.

MD est fait pour être ouvert et modifié. Gardez le fichier dans ce format tant que le travail dure, et exportez depuis lui chaque fois qu’une version finie est nécessaire.

Markdown existe parce qu’écrire du HTML à la main est fastidieux et qu’écrire dans un traitement de texte produit un fichier que personne ne peut diff. C’est un ensemble de conventions qui étaient déjà utilisées dans le courriel en texte brut bien avant d’avoir un nom : une ligne commençant par un dièse est un titre, des astérisques autour d’un mot le mettent en gras, un trait d’union au début d’une ligne fait une puce. L’idée est que la source reste lisible même pour quelqu’un qui n’a jamais entendu parler du format.

Cette propriété est la raison pour laquelle il a conquis la documentation. Un README, un changelog, une note technique ou un article de blog écrits en Markdown est un fichier texte — il va dans le contrôle de version, deux personnes peuvent l’éditer et fusionner le résultat, et un relecteur peut lire le diff sans rien rendre. Aucun format binaire de traitement de texte ne permet rien de tout cela.

Il n’y a pas un seul Markdown. La description originale de 2004 était informelle et laissait beaucoup de points indécis, donc les implémentations ont comblé les vides différemment. CommonMark est la tentative sérieuse de spécification précise et c’est ce que suivent la plupart des éditeurs modernes. GitHub Flavored Markdown est CommonMark plus une poignée d’extensions, et c’est la version que la plupart des gens ont réellement utilisée.

L’extension qui cause le plus de confusion est celle des tableaux. Les tableaux délimités par des barres verticales ne font pas partie de CommonMark — c’est une extension GitHub, également supportée par beaucoup d’éditeurs et par de nombreux générateurs de sites statiques, et absente des implémentations strictes. Un tableau qui s’affiche parfaitement dans un dépôt et sort comme une rangée de tuyaux ailleurs n’est pas un fichier cassé ; c’est un fichier qui utilise une extension que l’autre outil n’implémente pas. Les listes de tâches, le barré et les liens automatiques sont des extensions de la même catégorie.

Beaucoup de fichiers Markdown s’ouvrent par un bloc encadré par trois traits d’union contenant quelque chose comme un titre, une date et une liste d’étiquettes. C’est le front matter — en général du YAML, parfois du TOML ou du JSON — et ce n’est pas du Markdown. Les générateurs de sites statiques, les applications de prise de notes et les constructeurs de documentation le lisent comme des métadonnées sur le document et le retirent avant le rendu.

Un outil qui ne connaît pas le front matter l’affiche comme du texte brut en haut de la page. Si un document converti commence par trois traits d’union et une liste de paires clé-valeur, c’est ce qui s’est passé, et supprimer le bloc avant la conversion est le correctif.

Il n’y a pas de taille de page, pas de marge, pas de police, pas d’interligne, pas de saut de page et pas de pied de page. C’est une caractéristique plutôt qu’une omission : le fichier décrit la structure — ceci est un titre, ceci est une citation, ceci est du code — et laisse l’apparence à ce qui le rend. Le même document devient une page web, un PDF et un jeu de diapositives sans être réécrit.

Il n’y a pas non plus de commentaires, pas de suivi des modifications et pas de moyen de dire « ce paragraphe est la troisième révision ». Le contrôle de version s’en charge, et s’en charge mieux, ce qui est le compromis que le format fait. Si un document a besoin d’un flux de revue plutôt que d’un historique, un traitement de texte est l’outil honnête.

La destination habituelle est le PDF, pour tout ce qui est envoyé à quelqu’un qui ne se soucie pas de ce dans quoi c’était écrit — un cahier des charges remis à un client, un jeu de notes, un manuel. La conversion transforme les marques structurelles en vrai formatage : les titres deviennent des titres, les blocs de code gardent leur police à chasse fixe, et les listes gardent leur imbrication.

HTML est l’autre cible courante, et c’est plus proche d’une traduction que d’une conversion puisque Markdown a été conçu comme un sténo pour lui. Convertir en DOCX vaut la peine d’être connu pour une situation précise : un document que vous voulez écrire dans un éditeur de texte et remettre à quelqu’un qui n’acceptera qu’un fichier Word avec suivi des modifications.

Un fichier Markdown qui montre six schémas ne contient aucun schéma. Il contient six chemins, et les images se trouvent à côté de lui sur le disque ou sur un serveur. Déplacez le fichier sans le dossier autour et chaque image disparaît.

Cela compte au moment de la conversion. Un convertisseur ne peut embarquer une image que s’il la trouve, donc les chemins relatifs doivent résoudre depuis l’endroit où le fichier se trouve réellement. Cela compte à nouveau quand un document est envoyé par courriel : envoyer à quelqu’un un fichier .md sans ressources, c’est lui envoyer le squelette. Si les images sont le sujet, convertissez en PDF, où tout finit à l’intérieur d’un seul fichier.

N’importe quel éditeur de texte suffit — Notepad, TextEdit, nano — parce que le fichier est du texte. C’est tout l’intérêt, et c’est pourquoi un document Markdown écrit en 2004 s’ouvre aujourd’hui avec rien d’installé.

Les éditeurs dédiés ajoutent un aperçu en direct, ce qui est réellement utile pendant l’écriture et complètement indifférent au fichier. Visual Studio Code, Obsidian et Typora rendent au fur et à mesure de la frappe ; aucun d’eux ne stocke quoi que ce soit que les autres ne puissent pas lire. En choisir un est une préférence, pas un engagement, ce qui est plus que ce qu’on peut dire de la plupart des formats de document.