Le Markdown que vous récupérez, et comment le nettoyer

Ce qu'est réellement la sortie

Le convertisseur produit du GitHub Flavored Markdown, le dialecte utilisé par GitHub, GitLab, Obsidian, les imports Notion et la plupart des générateurs de sites statiques. C'est du CommonMark plus quelques ajouts, dont le seul qui compte ici : les tableaux à barres verticales.

Ce choix est délibéré. Le CommonMark pur n'a aucune syntaxe de tableau, si bien qu'un convertisseur qui le viserait supprimerait les tableaux ou produirait du HTML brut. Les tableaux GFM se lisent comme du texte et sont compris à peu près partout où Markdown l'est.

Ce qui survit au trajet

Les cinq retouches à faire à chaque fois

La plupart des fichiers convertis demandent le même petit jeu de passes. Elles prennent deux minutes et font la différence entre un fichier qu'on peut chercher et un fichier qu'on peut lire.

• Corrigez l'échelle des titres. Les seuils de taille produisent des niveaux localement justes et globalement inégaux — un document peut finir avec trois H1 et aucun H2. Parcourez les titres seuls et renumérotez pour que l'imbrication corresponde au vrai plan du document.
• Recollez les paragraphes scindés. Un document généreusement interligné coupe les paragraphes aux fins de ligne. Cela se lit comme un empilement de lignes courtes ; joignez-les et supprimez les lignes vides parasites.
• Réparez la césure. Un texte justifié avec césure en marge droite laisse des mots coupés entre deux lignes : « conver- » puis « sion ». Cherchez dans le fichier un trait d'union suivi d'un saut de ligne.
• Vérifiez chaque tableau. Comptez les colonnes du Markdown par rapport à l'original, et contrôlez la dernière rangée — la rangée finale est la victime la plus fréquente. Un tableau qui a perdu sa forme est en général plus rapide à ressaisir qu'à réparer.
• Supprimez le mobilier de page. Les en-têtes et pieds courants sont détectés et retirés, mais un document qui les fait varier — un titre de chapitre différent à chaque page — peut laisser des fragments.

Une note sur les tableaux

Un tableau GFM exige le même nombre de cellules dans chaque rangée, et la rangée de séparation de l'en-tête fixe le nombre de colonnes pour tout le tableau. Si le convertisseur compte mal une rangée, le tableau est invalide et s'affiche en texte littéral avec des barres verticales.

C'est un échec visible, ce qui est une chance : vous le verrez tout de suite plutôt que de le découvrir plus tard. Un tableau comme celui-ci est cassé :

| Région | T1 | T2 |
| --- | --- | --- |
| Nord | 120 | 140 |
| Sud | 95 |
| Est | 88 | 102 |

La réparation

Ajoutez la cellule manquante, vide si la cellule d'origine l'était. Chaque rangée doit comporter autant de barres que la rangée de séparation.

| Région | T1 | T2 |
| --- | --- | --- |
| Nord | 120 | 140 |
| Sud | 95 |  |
| Est | 88 | 102 |

L'échappement, et pourquoi la sortie contient parfois des antislashs

Markdown donne un sens à des caractères qui apparaissent dans la prose ordinaire. Une astérisque signifie l'emphase, un tiret bas aussi, un dièse en début de ligne signifie un titre, un nombre suivi d'un point en début de ligne signifie un élément de liste.

Quand ces caractères figurent dans votre document pour eux-mêmes — un appel de note, un nom de variable avec des tirets bas, une ligne qui commence réellement par « 1985. » — il faut les échapper par un antislash, sinon ils changent silencieusement le rendu du document. Un antislash dans la sortie, c'est en général le convertisseur qui prend ses précautions, pas une erreur.

Si un antislash vous gêne, le supprimer est sans risque tant que vous vérifiez ensuite le rendu de la ligne.

Où va le fichier ensuite

Markdown est du texte brut, et c'est la raison même de convertir : il se cherche avec grep, se compare avec diff, et restera lisible dans cinquante ans par tout ce qui sait ouvrir un fichier texte.

Pour un dépôt, mettez-le dans l'arborescence et laissez la revue de code faire son travail. Pour un coffre de notes, vérifiez d'abord l'échelle des titres, car la plupart en tirent leur plan. Pour un site statique, ajoutez le front matter dont votre générateur a besoin — aucun convertisseur ne peut l'inventer, puisqu'il n'est pas dans le PDF. Pour alimenter un modèle de langage, voyez le guide sur la préparation des PDF pour la recherche documentaire : c'est un autre travail, avec d'autres priorités.