Markdown-Diff: Zwei Markdown-Dateien online vergleichen
Fügen Sie zwei Markdown-Dokumente ein und sehen Sie zeilenweise, was sich geändert hat. Funktioniert mit READMEs, Release Notes, MDX und Dokumenten mit Frontmatter. Der Diff läuft im Browser.
Was ist das Markdown-Diff-Tool?
Ein kostenloses Browser-Tool, um zwei Markdown-Dokumente auf Quelltext-Ebene zu vergleichen. Fügen Sie ein altes README.md links ein, das aktualisierte rechts, und jede geänderte Überschrift, Listenzeile, Verlinkung, jeder Codeblock und jede Tabellenzelle leuchtet auf. Nichts verlässt Ihr Gerät.
Der Diff arbeitet zeichenweise. Markdown ist reiner Text, also ist das die richtige Primitive: Sie sehen die buchstäbliche Änderung am Dokument-Quelltext, keine Vermutung darüber, wie ein Renderer sie auslegen würde.
Wenn Sie unseren Text-Diff bereits für allgemeine Prosa einsetzen, ist die Markdown-Seite dieselbe Engine mit Texten, die auf Fälle aus dem echten Doku-Alltag zugeschnitten sind. Für die YAML-Frontmatter-Blöcke ganz oben in Jekyll-, Hugo- oder MkDocs-Dateien geht die YAML-Seite besser mit der einrückungsempfindlichen Struktur um. Strenge strukturierte Daten mit Schlüssel/Wert-Lookups gehören in den JSON-Diff.
Wie der Diff tatsächlich arbeitet
Der Diff ist auf Zeichen-Ebene. Nach dem rohen Diff verschiebt eine semantische Bereinigungspass die Hervorhebungen so, dass sie auf ganzen Wörtern, Listenzeilen und Linkzielen landen, statt einen `code span` mittendrin zu zerschneiden oder das führende ## einer Überschrift abzutrennen. Einfügungen erscheinen rechts grün, Löschungen links rot.
Es ist ein Quelltext-Diff, kein Diff der gerenderten Ausgabe. Das ist die richtige Primitive für Markdown-Arbeit, und es zählt mehr, als es klingt. Zwei Dokumente, die zu identischem HTML rendern, können sehr unterschiedliche Quelltexte haben: **fett** gegen __fett__, Aufzählungspunkte mit * gegen -, vier Leerzeichen Einrückung gegen einen Tab in einer verschachtelten Liste. Ein Renderer plättet das alles zur gleichen Ausgabe und das Signal geht verloren. Wenn Sie wissen wollen, ob ein Beitragender wirklich nur einen Tippfehler korrigiert hat, beantwortet das der Quelltext-Diff.
Markdown ist außerdem eine Familie von Dialekten. Die Originalspezifikation von John Gruber (siehe daringfireball.net) war bewusst lose, und mit der Zeit zogen CommonMark, GitHub Flavored Markdown, Pandoc und MultiMarkdown jeweils in eine andere Richtung. Tabellen gibt es in GFM und Pandoc, aber nicht in CommonMark. Durchstreichen mit ~~ und Aufgabenlisten mit - [ ] sind GFM-Erweiterungen. Das Diff-Tool kümmert sich nicht um den Dialekt; es zeigt den Rohtext. Der Geschmack zählt, sobald Sie fragen, ob ein Absatz im neuen Doku-Theme noch richtig rendert, was eine Frage an Ihren Renderer ist, nicht an den Diff.
Markdown in drei Schritten vergleichen
Zwei Textfenster, ein Diff. Keine Anmeldung, kein Upload, kein Server-Hin-und-zurück.
- 1
Markdown einfügen oder hochladen
Fügen Sie die alte Version links und die neue rechts ein. Oder klicken Sie auf Hochladen in einem der Fenster, um eine .md-, .markdown- oder .mdx-Datei zu laden. Der Beispiel-Button füllt beide Seiten mit einem kleinen README, damit Sie den Diff in Aktion sehen, bevor Sie eigene Inhalte einfügen.
- 2
Bei Bedarf Zeilenenden vereinheitlichen
Eine unter Windows bearbeitete Datei hat üblicherweise CRLF-Zeilenenden; eine Datei von einem Linux-Server LF. Ein zeichenbasierter Diff behandelt das als unterschiedlich, was jede Zeile als geändert anmalen kann. Wenn der Diff verdächtig voll mit Rot und Grün aussieht, vereinheitlichen Sie zuerst beide Dateien im Editor auf dasselbe Zeilenende. VS Code zeigt das aktive Zeilenende in der unteren Statusleiste.
- 3
Den Diff lesen
Löschungen erscheinen links rot, Einfügungen rechts grün. Beide Fenster scrollen synchron. Frontmatter-Blöcke, Code-Fences, Tabellenzeilen und Listenpunkte sind für die Diff-Engine alle nur Text, also tauchen Änderungen darin genauso auf wie Änderungen am Fließtext. Die Änderungszähler in den Kopfzeilen geben einen schnellen Eindruck davon, wie tiefgreifend bearbeitet wurde.
Wann der Markdown-Diff das richtige Werkzeug ist
README-Änderungen zwischen PR-Branches prüfen
Sie wollen schnell sehen, was sich an README.md in einem PR-Branch gegenüber main geändert hat, möchten aber nicht GitHub öffnen, an der gerenderten Vorschau vorbeiscrollen und drei Menüs tief auf "Display the source diff" klicken. Fügen Sie stattdessen die beiden Rohdateien in dieses Tool ein. Überschriften, Code-Fences und Linkziele kommen klar heraus. Praktisch, wenn der PR auch hundert Quelldateien anfasst und die Doku-Änderung im Rauschen untergeht.
Release Notes V1 und V2 vor der Veröffentlichung vergleichen
Release Notes durchlaufen vor der Veröffentlichung mehrere Bearbeitungsrunden. Entwürfe werden umsortiert, Punkte zusammengeführt, Versionsnummern verschieben sich. Ein Diff zwischen den zuletzt veröffentlichten RELEASE_NOTES.md und dem neuen Entwurf fängt verlorene Einträge und versehentliche Doppelungen ab, was die gerenderte Vorschau schlecht kann, weil das Auge über ähnlich aussehende Zeilen gleitet. Der Diff macht es außerdem einfach zu prüfen, ob die ## Breaking changes-Sektion zwischen den Releases tatsächlich gewachsen ist.
CMS-Export gegen das Quell-Repository diffen
Ihr Team schreibt Doku in Markdown in einem Git-Repo, aber die öffentliche Seite wird von einem CMS oder Static-Site-Generator wie MkDocs, Hugo oder Docusaurus erzeugt. Gelegentlich driftet die veröffentlichte Seite vom Quelltext ab: Jemand hat die Live-Seite über die CMS-UI bearbeitet und vergessen zurückzuschieben, oder ein CI-Schritt hat die Datei umgeschrieben. Exportieren Sie die veröffentlichte Seite als Markdown, legen Sie sie in ein Fenster, das .md aus dem Repo in das andere, und der Drift liegt in Sekunden vor Ihnen.
Blogbeitrag-Entwurf gegen Lektorats-Revisionen
Sie haben einen Blogbeitrag in Markdown an einen Lektor geschickt. Der Lektor hat eine markierte Fassung zurückgegeben. Ein Diff zwischen beiden ist ein viel schnellerer Weg, das Feedback aufzunehmen, als Absatz für Absatz neu zu lesen, vor allem wenn Sektionen umgestellt oder die Einleitung neu geschrieben wurde. Funktioniert genauso gut für Ghostwriter-Inhalte, bei denen die schreibende Person bestätigen muss, welche Stiltöne den Lektoratsdurchgang überlebt haben.
Eine Markdown-zu-MDX-Migration prüfen
Eine Docusaurus- oder Astro-Seite von .md nach .mdx zu migrieren klingt nach einer harmlosen Aktion, bis Sie feststellen, dass Imports verschoben wurden, JSX-Komponenten frühere Markdown-Tabellen ersetzt haben und einige Code-Fences nun in eigene Komponenten verpackt sind. Diffen Sie die alte page.md gegen die neue page.mdx Datei für Datei, und die Migrationsentscheidungen werden überprüfbar. Derselbe Ablauf rückwärts, falls Sie entscheiden, dass MDX ein Fehler war, und auf reines Markdown zurückwollen.
Markdown-Kurzreferenz
Ein knapper Spickzettel zu den Syntax-Sonderfällen, die dieses Tool am häufigsten zutage fördert. Die Dialekt-Spalte sagt, welche Geschmacksrichtungen das Feature wirklich unterstützen, denn von dort kommen die meisten Renderer-Überraschungen.
| Topic | What this tool does |
|---|
| Drift zwischen Geschmacksrichtungen | Markdown ist eine Familie. CommonMark ist die De-facto-Basis. GFM ergänzt Tabellen, Aufgabenlisten, Durchstreichen und Auto-Links. Pandoc und MultiMarkdown ergänzen Fußnoten, Definitionslisten und mehr. Dieselbe Quelle kann zwischen ihnen sehr unterschiedlich rendern. |
|---|
| Tabellen | Pipe-Tabellen gibt es in GFM und Pandoc. Sie gehören nicht zu CommonMark oder dem Original-Markdown. Wenn ein Renderer rohe |-Zeichen statt Zellen ausgibt, ist der Parser CommonMark-strikt und Sie brauchen einen GFM-kompatiblen. |
|---|
| Durchstreichen | ~~Text~~ ist eine GFM-Erweiterung. Original-Markdown und CommonMark unterstützen es nicht. Pandoc unterstützt es mit aktivierter strikeout-Erweiterung. Wenn Ihr Text mit literalen Tilden rendert, kennt der Renderer GFM nicht. |
|---|
| Aufgabenlisten | - [ ] todo und - [x] erledigt sind eine GFM-Erweiterung. CommonMark rendert sie als einfache Aufzählungspunkte mit literalen Klammern. GitHub, GitLab und die meisten modernen Doku-Sites unterstützen sie; gewöhnliche Markdown-Prozessoren in der Regel nicht. |
|---|
| Codeblöcke: gefenct vs. eingerückt | Gefencete Codeblöcke (drei Backticks oder Tilden, mit optionalem Sprach-Tag) sind CommonMark und überall unterstützt. Die Originalspezifikation hatte nur Codeblöcke mit vier Leerzeichen Einrückung; die funktionieren weiter, können aber keinen Sprach-Hinweis tragen. Beides in einer Datei zu mischen ist erlaubt, aber unsauber. |
|---|
| Harte Zeilenumbrüche | Drei Optionen: eine Zeile mit zwei abschließenden Leerzeichen beenden, mit einem Backslash \ beenden (CommonMark und GFM, nicht Original) oder eine Leerzeile für einen Absatzumbruch einfügen. Abschließende Leerzeichen sind in den meisten Editoren unsichtbar, weshalb harte Umbrüche oft Diffs überleben, die kein Mensch entdeckt. |
|---|
| Frontmatter | YAML zwischen ----Fences, TOML zwischen +++ oder JSON zwischen { } ganz oben in der Datei. Gehört nicht zur Markdown-Spezifikation, ist aber in Jekyll, Hugo, MkDocs, Docusaurus und Astro allgegenwärtig. Renderer entfernen es, bevor sie den Rumpf parsen. |
|---|
| Inline-HTML | CommonMark erlaubt rohe HTML-Tags in Markdown. GFM auch, wendet beim Rendern auf github.com aber einen HTML-Sanitizer an. Manche Static-Site-Generatoren bereinigen, manche lassen HTML durch, einige escapen es. Diffs von Seiten mit eingebetteten <div>- oder <iframe>-Blöcken sind in Migrations-Audits üblich. |
|---|
Markdown-Diff: häufige Fragen
Zeigt das eine Vorschau der gerenderten Ausgabe?
Nein. Das Tool diffed den Markdown-Quelltext, nicht das HTML, das ein Renderer erzeugen würde. Das ist Absicht. Zwei Dokumente können dasselbe HTML rendern und trotzdem deutlich unterschiedliche Quelltexte haben, etwa Aufzählungen mit * gegen - oder Fettdruck mit ** gegen __. Ein Diff auf Quelltext-Ebene erhält dieses Signal. Wenn Sie sehen wollen, wie das Dokument rendert, fügen Sie es in Ihre übliche Vorschau ein: GitHub-Web-UI, VS Code oder Ihren Static-Site-Generator.
Worin unterscheidet sich das vom Vergleich gerenderten HTMLs?
Ein Diff über gerendertes HTML sagt Ihnen, was die Lesenden sehen. Ein Quelltext-Diff sagt Ihnen, was tatsächlich in der Datei geändert wurde. Sie beantworten unterschiedliche Fragen. Für Markdown ist der Quelltext-Diff fast immer der nützlichere, weil er die Edits der schreibenden Person treu zeigt: Eine Überschriftenebene wechselte von ## auf ###, ein Code-Block hat den Sprach-Tag getauscht, ein relativer Link wurde absolut. Wenn Sie HTML-Vergleich wollen, jagen Sie beide Dateien zuerst durch Ihren Renderer und diffen Sie die Ausgabe.
Was ist mit der Mehrdeutigkeit zwischen CommonMark und GitHub Flavored Markdown?
Der Diff selbst parst kein Markdown, der Dialekt ist ihm also egal. Tabellen, Aufgabenlisten, Durchstreichen und Auto-Links sehen einfach wie Text aus. Der Geschmack zählt, wenn Sie fragen, ob Ihr Dokument noch korrekt rendert. CommonMark kommt einer Basisspezifikation am nächsten, und GitHub Flavored Markdown ist CommonMark plus Tabellen, Aufgabenlisten, Durchstreichen und Auto-Links. Wählen Sie das, was Ihr Ziel-Renderer unterstützt.
Wie wird YAML- oder TOML-Frontmatter behandelt?
Frontmatter ist nur Text am Dateianfang, eingerahmt von --- für YAML oder +++ für TOML. Static-Site-Generatoren wie Hugo, Jekyll und MkDocs nutzen das für Seiten-Metadaten. Der Diff behandelt den Block wie gewöhnlichen Text, also erscheinen Änderungen an title:, date: oder tags: wie jede andere Zeile. Wenn Ihr Frontmatter groß und einrückungsempfindlich ist, ist unsere YAML-Diff-Seite für diesen Block isoliert die bessere Wahl.
Funktioniert es für MDX oder JSX innerhalb von Markdown?
Ja. MDX ist Markdown mit eingebetteten JSX-Komponenten, und das JSX ist aus Sicht des Diffs einfach mehr Text. Sie können eine .mdx-Datei in eines der Fenster einfügen, und der Diff bringt Änderungen an Imports, Komponenten-Props und dem umliegenden Markdown genauso heraus, wie er es bei .md tut. Das Einzige, was das Tool nicht tut, ist zu validieren, dass Ihr JSX kompiliert; das ist Aufgabe des MDX-Compilers. Für reine Code-Sicht der JSX-Stellen fügen Sie sie in unseren Text-Diff ein.
Wie werden Zeilenenden (CRLF vs. LF) gehandhabt?
Zeilenenden sind Zeichen, also liefern eine im Windows-Stil mit CRLF gespeicherte Datei und eine im Unix-Stil mit LF an jeder Zeile einen Unterschied. Wenn Ihre Fenster voller Phantomänderungen wirken, ist das fast immer die Ursache. Die Lösung: Vereinheitlichen Sie beide Dateien vor dem Einfügen im Editor auf dasselbe Zeilenende; in VS Code wird das aktive Zeilenende in der unteren Statusleiste angezeigt und ist mit einem Klick wechselbar. Auch Gits Einstellung core.autocrlf kann zwischen Maschinen für überraschende CRLF-Unterschiede sorgen.
Datenschutz und wie das funktioniert
Ihr Markdown verlässt nie Ihren Browser. Editor, Diff und Formatter laufen alle auf Ihrer Maschine. Keine Analytik auf Ihrer Eingabe, keine Logs, kein Server-Hin-und-zurück. Hintergrundlektüre zum Format selbst gibt es bei Wikipedia, die aktuelle CommonMark-Spezifikation auf spec.commonmark.org/0.31.2 und die GitHub-Variante auf github.github.com/gfm.