Markdown original

Markdown modifié

Diff Markdown : comparer deux fichiers Markdown en ligne

Collez deux documents Markdown et voyez ce qui a changé, ligne par ligne. Fonctionne sur les README, les notes de version, le MDX et les docs avec frontmatter. Le diff tourne dans votre navigateur.

Qu'est-ce que l'outil de diff Markdown ?

Un outil gratuit, entièrement dans le navigateur, pour comparer deux documents Markdown au niveau du texte source. Collez un ancien README.md à gauche, le nouveau à droite, et chaque titre, élément de liste, lien, bloc de code et cellule de tableau modifié s'allume. Rien ne quitte votre machine.

Le diff fonctionne caractère par caractère. Markdown est du texte brut, donc c'est la primitive correcte : vous voyez le changement réel dans la source du document, pas une supposition sur l'interprétation d'un moteur de rendu.

Si vous utilisez déjà notre diff de texte pour la prose en général, la page Markdown est le même moteur avec des explications adaptées aux cas qui surviennent quand on rédige vraiment de la documentation. Pour comparer les blocs de frontmatter YAML en tête des fichiers Jekyll, Hugo ou MkDocs, la page YAML gère mieux la structure sensible à l'indentation. Les données structurées strictes avec recherches clé/valeur relèvent du diff JSON.

Comment fonctionne le diff en pratique

Le diff est au niveau du caractère. Après le diff brut, une passe de nettoyage sémantique recale les surlignages pour qu'ils tombent sur des mots entiers, des éléments de liste et des cibles de liens, plutôt que de couper un `code span` en plein milieu ou de séparer le ## de tête d'un titre. Les insertions s'affichent en vert à droite, les suppressions en rouge à gauche.

C'est un diff de texte source, pas un diff de sortie rendue. C'est la bonne primitive pour le travail Markdown, et ça compte plus qu'il n'y paraît. Deux documents qui rendent un HTML identique peuvent avoir des sources très différentes : **gras** contre __gras__, puces avec * contre -, indentation à quatre espaces contre tabulation pour une liste imbriquée. Un moteur de rendu aplatit tout cela dans la même sortie et vous perdriez le signal. Quand vous voulez savoir si un contributeur a vraiment juste corrigé une coquille, c'est le diff source qui répond.

Markdown est aussi une famille de dialectes. La spec d'origine de John Gruber (voir daringfireball.net) était volontairement souple, et au fil du temps CommonMark, GitHub Flavored Markdown, Pandoc et MultiMarkdown ont chacun tiré dans une direction différente. Les tableaux existent en GFM et Pandoc mais pas en CommonMark. Le barré avec ~~ et les listes de tâches avec - [ ] sont des extensions GFM. L'outil de diff se moque du dialecte ; il affiche le texte brut. La saveur compte quand vous commencez à vous demander si un paragraphe rend toujours correctement avec le nouveau thème de docs, ce qui est une question pour votre moteur de rendu, pas pour le diff.

Comparer du Markdown en trois étapes

Deux panneaux de texte, un diff. Pas d'inscription, pas d'envoi, pas d'aller-retour serveur.

1
Collez ou téléversez votre Markdown
Collez l'ancienne version à gauche, la nouvelle à droite. Ou cliquez sur Téléverser dans l'un des panneaux pour charger un fichier .md, .markdown ou .mdx. Le bouton Exemple remplit les deux côtés avec un petit README pour voir le diff fonctionner avant de coller votre propre contenu.
2
Normalisez les fins de ligne si besoin
Un fichier édité sous Windows a généralement des fins CRLF ; un fichier issu d'un serveur Linux utilise LF. Un diff caractère traite cela comme différent, ce qui peut peindre toutes les lignes comme modifiées. Si le diff a l'air anormalement plein de rouge et de vert, normalisez les deux fichiers à la même fin de ligne dans votre éditeur d'abord. VS Code montre la fin active dans la barre d'état en bas.
3
Lisez le diff
Les suppressions s'affichent en rouge à gauche, les insertions en vert à droite. Les deux panneaux défilent ensemble. Les blocs de frontmatter, les clôtures de code, les lignes de tableau et les éléments de liste ne sont que du texte pour le moteur de diff, donc les changements à l'intérieur ressortent comme ceux du corps du texte. Les compteurs de modifications dans chaque en-tête vous donnent une mesure rapide de l'ampleur de l'édition.

Quand le diff Markdown est le bon outil

Examiner les changements de README entre branches d'une PR

Vous voulez voir vite ce qui a changé dans README.md sur une branche de PR par rapport à main, mais vous ne voulez pas ouvrir GitHub, faire défiler la prévisualisation rendue et cliquer sur "Display the source diff" trois menus plus loin. Collez plutôt les deux fichiers bruts dans cet outil. Titres, clôtures de code et cibles de liens ressortent clairement. Pratique quand la PR touche aussi cent fichiers source et que la modif des docs se perd dans le bruit.

Comparer les notes de version V1 et V2 avant publication

Les notes de version passent par plusieurs éditions avant de sortir. Les brouillons sont réordonnés, les puces fusionnées, les numéros de version bougent. Differ les RELEASE_NOTES.md publiés précédemment contre le nouveau brouillon attrape les entrées disparues et les doublons accidentels, là où la prévisualisation rendue est mauvaise parce que l'œil glisse sur des lignes qui se ressemblent. Le diff facilite aussi la vérification que la section ## Breaking changes a vraiment grossi entre versions.

Differ un export de CMS contre le dépôt source

Votre équipe écrit la doc en Markdown dans un dépôt Git, mais le site public est généré par un CMS ou un générateur statique comme MkDocs, Hugo ou Docusaurus. Parfois la page publiée dérive de la source : quelqu'un a édité la page en direct via l'UI du CMS et a oublié de pousser, ou une étape de CI a réécrit le fichier. Exportez la page publiée en Markdown, déposez-la dans un panneau, déposez le .md du dépôt dans l'autre, et l'écart est devant vous en quelques secondes.

Brouillon de billet de blog contre relectures de l'éditeur

Vous avez envoyé un billet à un éditeur en Markdown. L'éditeur a renvoyé une version annotée. Un diff entre les deux est bien plus rapide pour absorber les retours que de relire paragraphe par paragraphe, surtout quand l'éditeur a réordonné des sections ou réécrit votre intro. Marche aussi pour le contenu écrit par un tiers où l'auteur doit confirmer quels ajustements de ton ont survécu à la passe d'édition.

Auditer une migration Markdown vers MDX

Migrer un site Docusaurus ou Astro de .md vers .mdx ressemble à une opération nulle, jusqu'à ce que vous découvriez que des imports ont bougé, que des composants JSX ont remplacé d'anciens tableaux Markdown bruts et que quelques clôtures de code sont désormais enveloppées dans des composants maison. Diffez l'ancien page.md contre le nouveau page.mdx fichier par fichier, et les choix de migration deviennent relisibles. Même flux dans l'autre sens si vous décidez que MDX était une erreur et voulez revenir à du Markdown brut.

Aide-mémoire Markdown

Une fiche courte sur les cas limites de syntaxe que cet outil fait remonter le plus souvent. La colonne dialecte vous indique les saveurs qui prennent en charge la fonctionnalité, parce que c'est de là que viennent la plupart des surprises entre moteurs de rendu.

Topic	What this tool does
Dérive entre saveurs	Markdown est une famille. CommonMark est la base de fait. GFM ajoute tableaux, listes de tâches, barré et autoliens. Pandoc et MultiMarkdown ajoutent notes de bas de page, listes de définitions et plus. Une même source peut rendre très différemment selon le moteur.
Tableaux	Les tableaux délimités par des barres existent en GFM et Pandoc. Ils ne font pas partie de CommonMark ni du Markdown d'origine. Si un moteur affiche des `\|` bruts au lieu de cellules, le parser est CommonMark strict et il vous faut un parser compatible GFM.
Barré	`~~texte~~` est une extension GFM. Le Markdown d'origine et CommonMark ne le supportent pas. Pandoc le supporte avec l'extension `strikeout` activée. Si votre texte s'affiche avec des tildes littéraux, le moteur n'est pas conscient de GFM.
Listes de tâches	`- [ ] à faire` et `- [x] fait` sont une extension GFM. CommonMark les rend en simples puces avec crochets littéraux. GitHub, GitLab et la plupart des sites de docs modernes les supportent ; les processeurs Markdown standard, en général non.
Blocs de code : clôturés vs indentés	Les blocs de code clôturés (trois backticks ou tildes, avec étiquette de langage optionnelle) sont CommonMark et universellement pris en charge. La spec d'origine n'avait que les blocs indentés à quatre espaces, qui marchent encore mais ne portent pas d'indication de langage. Mélanger les deux dans un fichier est légal mais brouillon.
Sauts de ligne forts	Trois options : terminer une ligne par deux espaces en fin, terminer par une barre oblique inverse `\` (CommonMark et GFM, pas le d'origine), ou insérer une ligne vide pour un saut de paragraphe. Les espaces en fin sont invisibles dans la plupart des éditeurs, raison pour laquelle les sauts forts survivent souvent à un diff qu'aucun humain ne repère.
Frontmatter	YAML entre clôtures `---`, TOML entre `+++` ou JSON entre `{ }` tout en haut du fichier. Pas du tout dans la spec Markdown mais omniprésent dans Jekyll, Hugo, MkDocs, Docusaurus et Astro. Les moteurs de rendu le retirent avant de parser le corps.
HTML en ligne	CommonMark autorise les balises HTML brutes dans le Markdown. GFM aussi mais applique un assainisseur HTML lors du rendu sur github.com. Certains générateurs statiques assainissent, d'autres laissent passer le HTML, quelques-uns l'échappent. Les diffs de pages avec des blocs `<div>` ou `<iframe>` intégrés sont fréquents lors d'audits de migration.

Diff Markdown : questions fréquentes

Cet outil prévisualise-t-il la sortie rendue ?

Non. L'outil diffère le texte source du Markdown, pas le HTML produit par un moteur de rendu. C'est volontaire. Deux documents peuvent rendre un HTML identique tout en ayant des sources notablement différentes, par exemple des puces écrites avec * au lieu de -, ou du gras écrit avec ** au lieu de __. Le diff au niveau source préserve ce signal. Si vous voulez voir comment le document s'affiche, collez-le dans votre prévisualiseur habituel : l'UI web de GitHub, VS Code ou votre générateur statique.

En quoi est-ce différent de comparer du HTML rendu ?

Un diff de HTML rendu vous dit ce que les lecteurs verront. Un diff source vous dit ce qui a vraiment changé dans le fichier. Ils répondent à des questions différentes. Pour Markdown, le diff source est presque toujours le plus utile parce qu'il montre fidèlement les modifications de l'auteur : un niveau de titre passé de ## à ###, un bloc de code clôturé qui change de tag de langage, un lien relatif devenu absolu. Si vous voulez une comparaison au niveau HTML, faites passer les deux fichiers par votre moteur de rendu d'abord et diffez la sortie.

Et l'ambiguïté entre CommonMark et GitHub Flavored Markdown ?

Le diff lui-même ne parse pas le Markdown, donc il se moque du dialecte que vous utilisez. Tableaux, listes de tâches, barré et autoliens ressemblent à du texte ordinaire. La saveur compte quand vous demandez si votre document s'affiche encore correctement. CommonMark est ce qui se rapproche le plus d'une spec de référence, et GitHub Flavored Markdown, c'est CommonMark plus tableaux, listes de tâches, barré et autoliens. Choisissez celui que votre moteur cible prend en charge.

Comment gère-t-il le frontmatter YAML ou TOML ?

Le frontmatter est juste du texte en haut du fichier, encadré par --- pour YAML ou +++ pour TOML. Les générateurs statiques comme Hugo, Jekyll et MkDocs s'en servent pour les métadonnées de page. Le diff traite ce bloc comme du texte ordinaire, donc les changements sur title:, date: ou tags: apparaissent comme n'importe quelle autre ligne. Si votre frontmatter est volumineux et sensible à l'indentation, notre page diff YAML est meilleure pour ce bloc isolé.

Est-ce que ça marche pour MDX ou JSX dans du Markdown ?

Oui. MDX, c'est du Markdown avec des composants JSX intégrés, et le JSX n'est que du texte de plus du point de vue du diff. Vous pouvez coller un fichier .mdx dans l'un des panneaux et le diff fera ressortir les changements d'imports, de props de composants et du Markdown environnant comme il le fait pour .md. La seule chose que l'outil ne fera pas, c'est valider que votre JSX compile ; c'est le boulot du compilateur MDX. Pour relire purement les morceaux JSX comme du code, collez-les dans notre diff de texte.

Comment sont gérées les fins de ligne (CRLF vs LF) ?

Les fins de ligne sont des caractères, donc un fichier enregistré en CRLF style Windows et un fichier enregistré en LF style Unix se diffèrent à chaque ligne. Si vos panneaux semblent pleins de changements fantômes, c'est presque toujours la cause. La solution est de normaliser les deux fichiers à la même fin de ligne dans votre éditeur avant de coller ; dans VS Code la fin active s'affiche dans la barre d'état en bas et change en un clic. Le réglage core.autocrlf de Git peut aussi introduire des différences CRLF surprises entre machines.

Confidentialité et fonctionnement

Votre Markdown ne quitte jamais votre navigateur. L'éditeur, le diff et le formateur tournent tous sur votre machine. Pas d'analytics sur votre saisie, pas de logs, pas d'aller-retour serveur. Pour aller plus loin sur le format, voyez l'article Wikipédia, la dernière spec CommonMark sur spec.commonmark.org/0.31.2 et la saveur GitHub sur github.github.com/gfm.