Formateur Markdown

Ce que fait un formateur Markdown

Le Markdown est tolérant. Vous pouvez écrire une puce avec -, * ou +, une emphase avec * ou _, et un titre avec une ligne de signes égal ou avec #. Cette liberté est pratique à la frappe, mais un fichier modifié par plusieurs personnes mélange vite tous les styles. Les tableaux se décalent, les lignes vides disparaissent et les diffs deviennent bruyants.

Ce formateur Markdown réécrit la source dans un style unique. Il repose sur Prettier, le formateur que la plupart des projets JavaScript utilisent déjà pour leur documentation, donc le résultat correspond à ce que donne Prettier dans VS Code ou en ligne de commande.

Mode d’emploi

1. Collez votre Markdown dans la zone de gauche, ou appuyez sur Ouvrir un fichier pour charger un fichier .md. Le collage le formate aussitôt.
2. Appuyez sur Exemple si vous voulez d’abord voir un exemple.
3. Choisissez l’Indentation, la Largeur de ligne et le Retour à la ligne : Garder tel quel, À la largeur de ligne ou Une ligne par paragraphe.
4. Appuyez sur Formater (ou Ctrl et Entrée) pour relancer après une modification.
5. Utilisez Copier ou Télécharger pour récupérer le résultat. Effacer vide la saisie.

Après un premier formatage, le résultat suit votre frappe.

Avant et après

Voici un court fichier écrit dans un style mélangé :

Project Notes
=============
* Install the tools
* Run the build
+ Deploy

|Name|Role|
|-|-|
|Ada|Admin|
|Linus|Editor|

Some *emphasis* and __bold__ text.

Le formateur renvoie :

Project Notes
=============

- Install the tools
- Run the build

* Deploy

| Name  | Role   |
| ----- | ------ |
| Ada   | Admin  |
| Linus | Editor |

Some _emphasis_ and **bold** text.

Plusieurs choses se sont produites. Une ligne vide suit maintenant le titre. La première liste utilise -. Le gras utilise ** et l’italique _. Les colonnes du tableau sont complétées pour s’aligner en texte brut. Remarquez que « Deploy » est resté à part : il utilisait une autre puce, donc le Markdown le traite comme une seconde liste, et le formateur garde ce sens en lui donnant un marqueur différent.

Couper les longs paragraphes

Avec Retour à la ligne réglé sur À la largeur de ligne et une largeur de 60, ce paragraphe :

Markdown files are easier to review when each paragraph follows the same rule for line length, because a diff then shows only the sentence that changed.

devient :

Markdown files are easier to review when each paragraph
follows the same rule for line length, because a diff then
shows only the sentence that changed.

Une ligne par paragraphe fait l’inverse et recolle les lignes coupées. Garder tel quel est le choix sûr par défaut quand vous ne savez pas ce que votre équipe attend.

Ce qu’il laisse tranquille

Le formateur change la mise en page, pas le sens. Certaines choses ne sont volontairement pas touchées :

• Les blocs de code. Le code d’un bloc délimité reste exactement tel quel. Un bloc marqué js contenant const a={b:1} n’est pas reformaté. Utilisez le formateur JavaScript pour cela.
• Les listes numérotées. Si chaque élément commence par 1., il garde 1. sur chaque ligne. Si vous avez numéroté 1, 2, 3, il garde cela.
• Le texte qui n’est pas une syntaxe valide. #Titre sans espace n’est pas un titre en CommonMark, il reste donc un paragraphe. Ajoutez l’espace et il devient un titre.
• Le HTML intégré. Les balises HTML dans votre Markdown sont gardées telles quelles.
• Votre texte. Les accents, les guillemets « » et les espaces insécables de la typographie française ne sont pas modifiés.

Conseils

• Formatez avant de commiter. Des fichiers cohérents font que le diff d’une pull request ne montre que les vraies modifications.
• Choisissez une seule règle de retour à la ligne pour tout un dépôt. Mélanger fichiers coupés et non coupés provoque de gros diffs la première fois que quelqu’un les formate.
• Construire un tableau à la main est long. Le générateur de tableau Markdown vous donne une grille où taper et accepte le collage depuis un tableur.
• Besoin de Markdown à partir d’une page web ou d’un fichier Word ? Utilisez le convertisseur HTML en Markdown ou le convertisseur Word en Markdown, puis rangez le résultat ici.

Autres façons de formater du Markdown

• VS Code : installez l’extension Prettier, ouvrez un fichier .md et lancez Mettre en forme le document. Le résultat correspond à cette page.
• Ligne de commande : npx prettier --write README.md formate un fichier sur place. Ajoutez --prose-wrap always pour couper les paragraphes.
• Linting : markdownlint vérifie des règles de style comme les niveaux de titres et la longueur des lignes. Il signale les problèmes, alors qu’un formateur corrige la mise en page pour vous. Beaucoup de projets utilisent les deux.

Limites

Le formateur suit CommonMark avec les extensions GitHub comme les tableaux et les listes de tâches. Les extensions d’autres outils, comme les conteneurs personnalisés ou les liens de wiki, sont traitées comme du texte simple et peuvent être espacées autrement que ce que l’outil attend. Le front matter en tête de fichier (le bloc entre deux lignes ---) est conservé. Les très gros fichiers fonctionnent, mais le formatage prend plus de temps puisque tout se passe sur votre appareil.